1. 从双击打不开的 HTML 说起js 引用其他 js 文件的真实场景前端项目一旦从单文件拆成多文件最先撞上的不是语法而是「为什么我双击 HTML 一片空白」。这个现象背后是 js 引用其他 js 文件的两种主流方式在打架传统script src和 ES Module 的import。前者靠全局变量串联后者靠模块作用域隔离加载顺序、路径解析、跨域策略完全不同。我见过太多同学把typemodule加上去之后控制台直接甩出Access to script at file:///... from origin null has been blocked by CORS policy然后开始怀疑人生。其实这不是代码写错了而是file://协议下浏览器对模块脚本的安全限制。传统脚本可以双击打开模块脚本不行这是规范决定的不是 bug。这篇文章聚焦一个具体场景你有一个index.html想引用js/api/request.js、js/modules/transcription.js这些拆分出来的文件同时希望本地联调时能统一走一个 API 通道而不是每个文件里散落着不同的 Key 和 Base URL。我会把两种引用方式的路径规则、加载顺序、类型声明讲清楚再给出可复制的 HTML 片段和模块导出示例最后用 TaoToken 的统一 Key 把本地请求验证跑通。适合谁看正在做前端多文件拆分、被import路径和 CORS 报错卡住、想让本地联调请求有统一出口的开发者。核心检索词就是 js 引用其他 js 文件、module import、script 加载顺序这几个词会贯穿全文。先说结论传统script适合快速原型和需要全局共享的工具函数ES Module 适合有明确依赖关系的业务拆分。两者可以共存但加载顺序和变量可见性必须心里有数。下面从路径和类型这两个最容易踩坑的点开始拆。2. TaoToken 前置统一 Key 与 API 通道的准备在讲配置之前先把「为什么需要统一 Key」说清楚。多文件拆分后常见做法是每个模块自己读环境变量或硬编码一个 Base URL。结果就是request.js里写一个地址transcription.js里又写一个联调时改一处漏一处控制台报 401 还得逐个文件翻。TaoToken 在这里的角色是一个统一的 API 通道你只需要在控制台生成一个 Key所有模块共用同一个 Base URL 和 Key请求验证、模型调用、额度查看都在一个地方完成。对前端多文件项目来说这意味着request.js封装一次其他模块 import 它就行不用重复配置。你需要先拿到三样东西Base URL、API Key、Model ID。Base URL 是https://taotoken.net/api注意这个地址不带任何查询参数直接作为请求前缀使用。API Key 在控制台的 API Keys 页面生成生成后只显示一次复制保存好。Model ID 根据你要调用的模型填写比如对话类、代码类各有对应的标识。具体操作路径打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 生成 Key然后在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 查看接入文档确认请求格式。如果你只是想先验证模型能不能通可以用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 里的模型对话页面快速试一次。这里有个容易忽略的点前端项目里直接暴露 API Key 是有风险的生产环境应该走后端代理。但本地联调阶段为了快速验证模块拆分后的请求链路可以先把 Key 放在一个单独的配置文件里并且把这个文件加入.gitignore。等联调通过再换成后端签发的临时凭证。我试过把 Key 写死在request.js里结果换环境时忘了改请求一直 401。后来改成从config.js读取config.js不提交到仓库问题就少了。这个习惯建议你一开始就养成。3. 可复制配置HTML 引入片段与模块导出示例这一节给出可以直接复制的代码。先看 HTML 里两种引用方式的写法再看模块文件怎么导出最后给出统一请求封装的配置片段。传统 script 标签的写法适合不需要模块作用域的工具函数script typetext/javascript srcjs/mixin/data-mixin.js/script script typetext/javascript srcjs/api/file-transcription.js/script script typetext/javascript srcjs/modules/file-transcription.js/script这种写法下每个文件里的顶层变量和函数都会挂到全局后面的脚本能直接访问前面的。加载顺序就是标签出现的顺序同步阻塞。双击 HTML 可以打开因为不涉及模块跨域。ES Module 的写法适合有明确依赖关系的业务代码script typemodule srcjs/main.js/script注意typemodule这个属性它带来三个变化脚本延迟执行相当于 defer、自动启用严格模式、拥有独立的模块作用域。模块内部的变量不会污染全局必须通过export和import显式传递。模块导出示例js/api/request.js// js/api/request.js const BASE_URL https://taotoken.net/api; const API_KEY window.__TAOTOKEN_KEY__ || your-key-here; const MODEL_ID your-model-id; export async function chatCompletion(messages) { const res await fetch(${BASE_URL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY} }, body: JSON.stringify({ model: MODEL_ID, messages }) }); if (!res.ok) { throw new Error(HTTP ${res.status}: ${await res.text()}); } return res.json(); }模块导入示例js/main.js// js/main.js import { chatCompletion } from ./api/request.js; const result await chatCompletion([ { role: user, content: 用一句话说明 ES Module 的加载顺序 } ]); console.log(result.choices[0].message.content);路径这里要特别注意./api/request.js是相对于当前模块文件的路径不是相对于 HTML。../表示上一级/开头表示站点根目录。少写.js后缀在某些构建工具里能过但浏览器原生 ES Module 要求写全扩展名否则报Failed to resolve module specifier。如果你用 Cline MCP 或 Claude Code 这类工具做本地开发配置里需要写全三件套。以 Claude Code 的 settings 为例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: your-key-here, ANTHROPIC_MODEL: your-model-id } }Codex 的auth.json同理Base URL、Key、Model ID 三个字段缺一不可。CC Switch 切换配置时也是围绕这三个值做文章。记住这个三件套后面排障会反复用到。4. 验证请求本地联调与成功结果确认配置写完之后必须验证请求真的能通。这一步不能省因为模块拆分后路径错误和 Key 错误的表现很像都是控制台一片红但原因完全不同。先启动本地服务。ES Module 不能用file://打开需要 HTTP 服务。用 Live Server 插件或者命令行起一个npx serve . # 或者 python3 -m http.server 8080然后访问http://localhost:8080/index.html打开控制台。如果看到chatCompletion返回的内容打印出来说明模块导入和请求链路都通了。成功的结果长这样控制台输出一段模型回复的文本Network 面板里能看到一个POST https://taotoken.net/api/v1/chat/completions请求状态码 200响应体里有choices数组。如果状态码是 401说明 Key 有问题如果是 404说明路径或 Base URL 拼错了如果是 CORS 报错说明你还在用file://打开。验证模型是否可用除了在代码里跑也可以直接用模型对话页面发一条消息确认 Key 和 Model ID 匹配。这一步能排除掉「Key 本身无效」和「代码写错」的混淆。实测下来最容易出问题的是 Base URL 末尾多写或少写斜杠。https://taotoken.net/api和https://taotoken.net/api/在拼接/v1/chat/completions时结果不同前者正确后者会变成双斜杠。建议在封装里统一处理比如用new URL()拼接避免手写字符串。还有一个细节ES Module 的顶层await在现代浏览器里支持但如果你要兼容旧环境需要把await包在 async 函数里。这个和模块加载本身无关但会影响你验证时的写法。5. 常见报错排查401、CORS、模块解析失败对照这一节把真实会遇到的报错列出来对照原因和解决方式。这些报错我在不同项目里都踩过按出现频率排序。报错信息触发场景原因解决方式Access to script at file:///... from origin null has been blocked by CORS policy双击打开含typemodule的 HTMLfile://协议下模块脚本被视为跨域用 Live Server 或npx serve起 HTTP 服务Failed to resolve module specifier ./api/requestimport 路径没写.js后缀浏览器原生模块要求完整路径补全.js扩展名401 Unauthorized请求返回 401API Key 错误、过期或未带上检查Authorization头确认 Key 从控制台复制完整local proxy failed本地代理配置错误Base URL 指向了不存在的本地代理确认 Base URL 为https://taotoken.net/api不要加多余路径Cannot read properties of undefined (reading choices)解析响应时响应结构不是预期的 OpenAI 格式或请求失败返回了错误对象先打印完整响应确认res.ok再取choicesOAuth error使用 Claude Code 等工具时认证方式配置冲突检查 settings 里是否同时存在 OAuth 和 API Key 配置保留一种net::ERR_ABORTED 404脚本路径错误HTML 里的src路径和实际文件位置不符用浏览器 Network 面板确认实际请求的 URL重点说两个。第一个是reading choices这个报错它本身不是根因根因是请求失败后返回了错误 JSON而代码直接去取choices。正确做法是先判断res.ok不 ok 就抛出带状态码的错误这样控制台能看到真正的原因。第二个是local proxy failed。这个报错通常出现在你配置了某个本地代理地址但代理服务没启动。解决方式是确认 Base URL 直接指向https://taotoken.net/api不要经过额外的本地转发层。如果你确实需要代理确保代理服务在运行且端口正确。还有一个隐蔽的坑多个script标签和typemodule混用时传统脚本里的全局变量在模块里访问不到因为模块作用域是隔离的。如果你在data-mixin.js里定义了window.helper模块里要用window.helper访问不能直接写helper。这个在拆分老项目时特别容易忘。排障时建议打开 Network 面板看实际发出的请求 URL、请求头、响应状态和响应体。控制台的报错信息往往只是表象Network 面板才能看到真相。6. 把统一 Key 用起来从本地联调到长期编码走到这里你已经能把 js 引用其他 js 文件的两种方式跑通也能用统一的 Base URL 和 Key 完成请求验证。接下来是怎么把这个配置用得更顺。如果你只是偶尔验证一下模型输出用模型对话页面就够了不用写代码。如果你在做长期的前端项目需要频繁调用模型能力建议把request.js封装成项目内的公共模块所有业务模块都 import 它。这样换 Key、换 Model ID 只改一个文件。对于需要长时间编码、跑 Agent 任务的场景Coding Plan 更适合它把额度管理和调用通道整合在一起不用每次手动配 Key。你可以根据自己项目的调用频率选择。最后给一个实用技巧把 Base URL、Key、Model ID 写在一个config.example.js里提交到仓库真正的config.js加入.gitignore。新同学拉代码后复制一份填自己的 Key 就能跑既统一了配置结构又不会泄露凭证。这个模式在多文件拆分项目里特别省心。代码写到最后能跑通、能排错、能复用比记住多少语法都重要。
