★ FEATURED ARTICLE 1. 组件库选型之后请求层才是真正要命的地方Vue3 TS UniApp 项目选组件库这件事华玥 hy-apphy-app/ui确实是目前比较省心的答案80 组件、全链路 TypeScript、easycom 自动引入、MIT 免费可商用装完基本就能直接写页面。但组件库只解决了「界面长什么样」真正决定项目能不能顺利跑起来的是另一件事——接口调用和鉴权配置怎么统一管理。我见过太多 uni-app 项目是这么写的登录页里uni.request写一遍 baseURL首页列表再写一遍个人中心又复制一份token 存在uni.getStorageSync(token)里每个页面自己去取、自己去拼 header。等到要换接口地址、要加统一签名、要处理 401 跳登录就得全局搜索替换改漏一处就是一个线上 bug。组件库选得再好请求层散着写项目照样会烂。这篇就接着华玥 hy-app 的接入往下走聚焦一个具体场景把 Vue3 TS UniApp 项目的请求层 endpoint 和鉴权配置统一收敛到 TaoToken 的 Key / API 通道上。TaoToken 是一个统一的大模型 API 接入平台你可以把它理解成「一个 Key 打通多家模型」的网关层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它本身不是组件库也不替代编辑器而是帮你把「请求发到哪、用哪个 Key、带什么鉴权头」这件事从业务代码里抽出来集中管理。适合谁看正在用或准备用 hy-app/ui 做 uni-app 多端项目的同学项目里uni.request已经散落多处、想统一收口的同学以及想把 AI 能力比如组件文档问答、表单智能填充接进自己 App、但不想每家模型单独对接的同学。下面从环境准备到一次真实连通性验证全部给可复制的配置。2. TaoToken 前置准备Key、Base URL 与模型 ID 三件套在动 uni-app 代码之前先把 TaoToken 这边的三样东西拿到手后面所有配置都围绕它们展开。这一步不复杂但顺序别乱否则后面排查会很痛苦。第一件是 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 Key。建议按项目或按环境命名比如uniapp-hy-app-dev、uniapp-hy-app-prod这样后面哪个 Key 用超了、要轮换一眼就能定位。创建完立刻复制保存页面刷新后通常就不再完整显示。这个 Key 就是后面请求头里Authorization: Bearer sk-xxxx的那串东西。第二件是 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api注意这里不带任何 UTM 参数代码里写的就是这个干净地址。所有请求路径都拼在它后面比如对话接口就是https://taotoken.net/api/v1/chat/completions。很多同学第一次接会把官网首页地址误当 API 地址填进去结果一直 404这个坑后面第五节会专门讲。第三件是 Model ID。TaoToken 支持多家模型具体可用列表和对应 ID 在 https://taotoken.net/doc 里能查到。Model ID 是区分大小写的字符串比如claude-sonnet-4-5、gpt-4o这类填错一个字符就会返回模型不存在的错误。建议先在文档里确认你要用的模型 ID抄下来别凭记忆写。如果你后面打算长期做编码类、Agent 类的调用可以顺手看一下 Coding Plan 页面 https://taotoken.net/coding-plan 它针对高频编码场景有更合适的额度方案只是想先验证链路通不通用按量 Key 就够了。想先在网页上直接试模型效果可以打开模型对话 https://taotoken.net/models 不用写代码就能发一条消息看看返回确认 Key 和模型 ID 没问题再往 uni-app 里搬。这里强调一个原则Key、Base URL、Model ID 这三样绝对不要硬编码在.vue或.ts业务文件里。UniApp 项目打包成小程序或 App 后代码是可被反编译查看的Key 写死在源码里等于公开。正确做法是走环境变量 请求层统一读取下一节就给完整模板。3. 可复制配置请求封装、环境变量与 settings 片段这一节是全文的核心目标是把请求层做成「改一处、全局生效」的结构。整体分三层环境变量文件存配置、请求封装文件做统一拦截、业务页面只调封装好的方法。华玥 hy-app 的组件负责 UI请求层我们自己搭两者互不干扰。先建环境变量文件。UniAppVite 版支持.env系列文件在项目根目录建三个# .env.development 开发环境 VITE_API_BASE_URLhttps://taotoken.net/api VITE_API_KEYsk-你的开发Key VITE_MODEL_IDclaude-sonnet-4-5 # .env.production 生产环境 VITE_API_BASE_URLhttps://taotoken.net/api VITE_API_KEYsk-你的生产Key VITE_MODEL_IDclaude-sonnet-4-5注意.env.production里的 Key 建议通过 CI 注入不要提交到 Git。在.gitignore里加上.env.production和.env.local只把.env.development的模板Key 留空提交上去给团队参考。接着写请求封装。在src/utils/request.ts里建一个基于uni.request的 Promise 封装统一注入 Base URL 和鉴权头// src/utils/request.ts const BASE_URL import.meta.env.VITE_API_BASE_URL const API_KEY import.meta.env.VITE_API_KEY interface RequestOptions { url: string method?: GET | POST | PUT | DELETE data?: Recordstring, any header?: Recordstring, string } export function requestT any(options: RequestOptions): PromiseT { return new Promise((resolve, reject) { uni.request({ url: ${BASE_URL}${options.url}, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, Authorization: Bearer ${API_KEY}, ...options.header, }, success: (res) { if (res.statusCode 200) { resolve(res.data as T) } else if (res.statusCode 401) { uni.showToast({ title: 鉴权失败请检查 Key, icon: none }) reject(res) } else { reject(res) } }, fail: (err) reject(err), }) }) }再包一层对话专用方法业务页面调它就行// src/utils/ai.ts import { request } from ./request const MODEL_ID import.meta.env.VITE_MODEL_ID export function chatCompletion(prompt: string) { return request({ url: /v1/chat/completions, method: POST, data: { model: MODEL_ID, messages: [{ role: user, content: prompt }], }, }) }如果你用的是支持 MCP 的 AI 编辑器比如 Cursor、Claude Code想让编辑器直接读华玥文档辅助写组件可以配一份 MCP 的 settings 片段。以 Claude Code 的配置为例在项目根目录建.mcp.json{ mcpServers: { hy-app-doc: { command: npx, args: [-y, hy-app/mcp], env: { HY_DOC_BASE: https://www.hy-design-uni.top } } } }这份配置让编辑器能读到华玥组件的实时文档生成组件代码时不会瞎编 API。它和 TaoToken 的请求层是两回事MCP 管的是「AI 编辑器怎么理解组件库」TaoToken 管的是「你的 App 运行时怎么调模型」别混在一起。最后在tsconfig.json里补上环境变量的类型声明让 TS 认识import.meta.env{ compilerOptions: { types: [hy-app/ui/global, vite/client] } }到这里配置层就齐了环境变量管地址和 Keyrequest.ts管统一注入ai.ts管业务调用。华玥组件照常用hy-input、hy-button请求走封装职责清晰。4. 验证请求一次真实的连通性测试与成功结果配置写完不能就算完必须跑一次真实请求确认链路通。这一步很多人跳过结果上线才发现 Key 没生效或者路径拼错。下面给一个最小可跑的验证页面用华玥组件搭个输入框和按钮点一下发一条消息。template view classtest hy-navbar titleTaoToken 连通性测试 :is-backfalse / hy-cell title提问 template #value hy-input v-modelprompt placeholder输入一句话 bordernone / /template /hy-cell view classtest__btn hy-button typeprimary block :loadingloading clickonSend 发送请求 /hy-button /view view v-ifresult classtest__result hy-text{{ result }}/hy-text /view /view /template script setup langts import { ref } from vue import { chatCompletion } from /utils/ai const prompt ref(用一句话介绍 uni-app) const loading ref(false) const result ref() const onSend async () { loading.value true result.value try { const res: any await chatCompletion(prompt.value) result.value res.choices?.[0]?.message?.content || 返回结构异常 } catch (e) { result.value 请求失败请看控制台 console.error(TaoToken 请求失败, e) } finally { loading.value false } } /script style langscss scoped .test { min-height: 100vh; background: #f5f5f5; __btn { padding: 40rpx; } __result { padding: 0 40rpx; } } /style跑起来后点「发送请求」预期结果是按钮进入 loading一两秒后下方显示模型返回的一句话。同时在开发者工具的 Network 面板里你能看到一条发往https://taotoken.net/api/v1/chat/completions的 POST 请求状态码 200请求头里带着Authorization: Bearer sk-...响应体是标准的choices数组结构。如果返回正常说明三件事都对了Base URL 拼对了、Key 有效、Model ID 存在。这时候你再去业务页面里调chatCompletion就是同一套链路不会再有意外。实测下来H5 端和小程序端用同一份封装代码都能跑通区别只在于小程序需要在后台配置 request 合法域名把https://taotoken.net加进白名单否则真机上会直接 fail。验证通过后建议把这条测试页保留在项目里比如放到pages/test/下不放进 tabBar后面换 Key、换模型、排查线上问题时它是最快的自检入口。5. 常见报错排查401、local proxy failed 与 reading choices链路跑不通时报错信息其实已经把答案写在脸上了只是很多人不看。下面按真实遇到的频率排一下对照着查。401 Unauthorized / 鉴权失败。最常见。原因通常是三种Key 没读到环境变量名写错比如写成了VITE_APIKEY而代码里读VITE_API_KEY、Key 前后带了空格或换行、Key 已失效或被删。排查方法在request.ts里临时console.log(API_KEY)看打印出来是不是完整的sk-开头字符串。如果是undefined就是环境变量没加载检查.env文件是否在项目根目录、变量名是否以VITE_开头Vite 只暴露这个前缀的变量。local proxy failed / 请求发不出去。这个报错一般出现在 H5 开发时配了 devServer 代理但代理目标写错或代理没启动。如果你没配代理直接请求https://taotoken.net/api正常不会出现这个。出现时先检查vite.config.ts里有没有残留的server.proxy配置指向了本地端口。另一个可能是小程序端没配合法域名真机调试时被拦截表现也类似「请求失败」。解决小程序后台把https://taotoken.net加入 request 合法域名。Cannot read properties of undefined (reading choices)。这个不是网络错误是响应结构和你预期的不一样。通常是请求其实失败了返回的是错误对象比如{ error: { message: ... } }但你的代码直接去取res.choices[0]于是报 reading choices。正确做法是先判断res.choices是否存在不存在就把res.error?.message打出来。上面第 4 节的示例里用了res.choices?.[0]?.message?.content || 返回结构异常就是为了兜住这种情况。看到这个报错先去看完整响应体别急着改代码。OAuth / 登录态相关报错。如果你在项目里同时接了用户登录体系注意区分「你的 App 用户登录」和「TaoToken 的 API Key 鉴权」两者是独立的。App 用户登录用你自己的后端TaoToken 用 Key。不要试图把 App 的 token 塞进 TaoToken 的 Authorization 头那必然 401。Key 就是 Key用户 token 就是用户 token分开存、分开用。模型不存在 / model not found。Model ID 拼错或者用了当前账号没权限的模型。去 https://taotoken.net/doc 核对准确的 ID 字符串注意大小写和连字符。改完 Model ID 记得重启 dev server环境变量改动不会热更新。排查顺序建议固定成先看 Network 里的状态码 → 再看请求头有没有 Authorization → 再看响应体完整内容 → 最后才怀疑代码逻辑。90% 的问题在前两步就能定位。6. 把请求层收口之后项目会变成什么样回到最开始那个场景组件库选型只是第一步请求层统一才是让项目能长期维护的关键。把 endpoint 和鉴权收敛到 TaoToken 之后你换来的是几个很实际的好处。换接口地址只改.env一个文件不用全局搜索uni.request加统一签名、统一重试、统一错误提示只在request.ts里加一次所有页面自动生效Key 轮换时改环境变量重新打包即可业务代码零改动。华玥 hy-app 负责把界面写快TaoToken 负责把请求管住两者各司其职项目结构就清爽了。如果你还想继续往下走几个入口按需取用想直接看模型返回效果去模型对话 https://taotoken.net/models 要管理或新建 Key去 API Keys https://taotoken.net/api-keys 查接口参数和模型列表看接入文档 https://taotoken.net/doc 长期做编码和 Agent 调用了解 Coding Plan https://taotoken.net/coding-plan 。官网总入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我踩过的坑环境变量改完一定要重启 dev serverVite 不会热更新.env小程序端记得配合法域名否则本地 H5 通了、真机不通会白白排查半天。把第 4 节那个测试页留着每次换 Key 或换模型先点一下比什么都快。
阅读完成 · 觉得有帮助？
