1. 为什么 dist 包在 VS Code 里直接打开会白屏前端项目打包之后源码会被压缩、拆分、按需加载最终产物统一丢进dist目录。很多人拿到dist的第一反应是双击index.html结果页面一片空白控制台报一堆Failed to load resource或者net::ERR_FILE_NOT_FOUND。这不是代码写错了而是浏览器用file://协议加载本地文件时对模块化脚本、绝对路径资源、fetch 请求都有严格限制。具体来说file://协议下会出现三类典型问题。第一类是 ES Module 的 CORS 限制浏览器不允许从file://加载typemodule的脚本直接报跨域错误。第二类是绝对路径失效打包工具通常把资源路径写成/assets/xxx.js在file://下这个/指向的是磁盘根目录而不是你的项目目录。第三类是接口请求前端代码里写的/stage-api/user/list在file://下没有 host请求根本发不出去。所以正确的做法是起一个本地 HTTP 服务把dist目录当作网站根目录托管起来。VS Code 里的 live-server 插件就是干这个的它能在你保存文件时自动刷新浏览器还能配置代理解决接口跨域。这套链路跑通之后你调试的就是真实的打包产物而不是开发环境的源码能提前发现很多只在生产构建里才暴露的问题。这篇文章面向的是需要本地联调 dist 包的前端同学尤其是那些后端接口在另一台机器、需要跨域代理的场景。我会从 live-server 的安装讲起给出settings.json的完整可复制配置再一步步验证代理是否生效最后把常见的报错对照着排查一遍。你跟着做基本能一次性把 dist 调试链路跑通。需要说明的是live-server 解决的是静态资源托管和请求转发它本身不产生接口数据。如果你的接口需要鉴权、需要模型能力那还得有一个能签发 Key 的服务端。后面我会讲到用 TaoToken 这类平台来补上接口这一环让本地调试的请求真正有响应。2. live-server 插件安装与 dist 目录的正确打开方式2.1 安装 live-server 插件打开 VS Code左侧活动栏点扩展图标搜索框输入live-server。排在第一位的通常是 Ritwick Dey 发布的那个图标是一个带闪电的圆圈安装量最高。点 Install几秒钟就装好了。装完之后你不需要重启 VS Code插件会自动激活。这里有个细节要注意网上有些教程让你装Live Server和Live Preview两个插件其实没必要。Live Preview是微软官方出的功能更偏向于内置预览窗口配置项和 live-server 不兼容。我们这篇只用一个避免settings.json里的配置互相打架。2.2 用 VS Code 单独打开 dist 目录这一步是很多人踩坑的地方。不要在你的源码工程根目录直接点 Go Live因为那样托管的根目录是工程根dist只是它的子目录访问路径会变成http://localhost:5555/dist/index.html资源路径全乱。正确做法是VS Code 菜单栏File→Open Folder选中你的dist目录本身。打开之后左侧资源管理器里应该直接看到index.html、assets文件夹、favicon.ico这些。确认根目录下就是index.html而不是还要再点一层。如果你用的是 monorepodist可能在packages/web/dist那就打开到dist这一层为止。判断标准很简单index.html必须是你打开目录的直接子文件。2.3 点击 Go Live 启动服务打开dist目录后看 VS Code 右下角状态栏会有一个Go Live的按钮。点它live-server 会立刻启动一个 HTTP 服务默认端口 5500注意不是 excerpt 里说的 55555555 是需要在配置里手动改的。浏览器会自动打开http://127.0.0.1:5500你的 dist 页面就出来了。如果右下角没看到Go Live检查两件事一是当前打开的是文件夹而不是单个文件二是 live-server 插件确实装好了。有时候状态栏图标被折叠了点一下状态栏最左边的...展开就能看到。启动之后控制台如果还有资源 404先别急着改代理先确认index.html里的资源路径是不是以/开头。如果是相对路径./assets/xxx.js那在根目录托管下也能正常加载。这一步过了说明静态资源托管没问题接下来才轮到跨域。3. settings.json 完整配置端口、代理与跨域一次配好3.1 打开 settings.json 的正确位置VS Code 的配置分两层用户级全局和工作区级当前项目。live-server 的代理配置建议放在工作区级因为不同项目的接口地址不一样。操作方式在dist目录下新建.vscode文件夹里面建一个settings.json。或者用快捷键CtrlShiftPMac 是CmdShiftP打开命令面板输入Preferences: Open Workspace Settings (JSON)VS Code 会自动帮你创建这个文件。放工作区级的好处是这份配置可以跟着项目走团队里其他人拉下来就能用不用每个人手动配一遍。3.2 可复制的完整配置片段下面这份配置可以直接粘进.vscode/settings.json路径和字段名都按 live-server 插件的实际读取规则来写{ liveServer.settings.host: localhost, liveServer.settings.port: 5555, liveServer.settings.wait: 1000, liveServer.settings.CustomBrowser: chrome, liveServer.settings.ChromeDebuggingAttachment: false, liveServer.settings.https: false, liveServer.settings.proxy: { enable: true, baseUri: /stage-api, proxyUri: http://192.168.17.11/stage-api }, liveServer.settings.ignoreFiles: [ .vscode/**, **/*.scss, **/*.sass, **/*.ts ] }逐项说明一下。host设成localhost如果你想让同局域网的其他设备访问可以改成0.0.0.0。port设成 5555和 excerpt 里保持一致避免和常见的 3000、8080 冲突。wait是文件变更后的刷新延迟单位毫秒1000 表示等 1 秒再刷新防止连续保存时反复刷新。CustomBrowser指定用 Chrome 打开方便调试。重点是proxy这一段。enable必须为true否则后面两项不生效。baseUri是前端代码里请求的路径前缀比如你代码里写fetch(/stage-api/user/list)那这里就填/stage-api。proxyUri是真实后端地址live-server 会把/stage-api开头的请求转发到这个地址。3.3 代理路径的匹配规则这里有个容易搞混的点baseUri和proxyUri的路径拼接关系。假设baseUri是/stage-apiproxyUri是http://192.168.17.11/stage-api那么前端请求/stage-api/user/list时实际转发到的是http://192.168.17.11/stage-api/user/list。也就是说baseUri会被替换成proxyUri后面的路径原样保留。如果你的后端接口没有/stage-api这个前缀比如真实地址是http://192.168.17.11/user/list那proxyUri就写http://192.168.17.11前端请求/stage-api/user/list会被转发成http://192.168.17.11/user/list。这个替换逻辑一定要对着你的接口文档确认清楚配错了就是 404。3.4 如果接口需要鉴权 Key有些接口不是裸奔的需要带 Token 或者 API Key。live-server 的代理本身不支持注入请求头这时候有两种做法。一种是在前端代码里统一加 header另一种是让后端网关做鉴权。如果你本地调试的是模型类接口需要 Key 才能返回数据可以到 TaoToken 的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite申请一个然后在请求里带上。注意 Key 不要硬编码进前端源码调试阶段可以用环境变量或者浏览器插件临时注入。配置改完之后必须重启 live-server 才生效。点一下状态栏的Port: 5555让它停掉再点Go Live重新启动。改配置不重启代理是不生效的这是最常见的「我明明配了怎么还跨域」的原因。4. 验证代理是否生效从请求到响应的完整链路4.1 用浏览器 Network 面板确认转发服务重启后打开http://localhost:5555按 F12 打开开发者工具切到 Network 面板。在页面上触发一次接口请求找到那条请求看它的 Request URL。如果显示的是http://localhost:5555/stage-api/user/list说明请求发给了本地服务这是对的。再看 Status Code如果是 200说明代理转发成功后端返回了数据。如果 Status Code 是 404点开这条请求看 Response通常是后端没有对应的路径。这时候回去检查proxyUri的拼接是否正确。如果 Status 是 502 或者ERR_CONNECTION_REFUSED说明 live-server 连不上proxyUri指向的地址检查后端服务是否启动、IP 和端口是否可达。4.2 用 curl 直接验证代理端点除了看浏览器还可以用命令行直接验证。打开终端执行curl -i http://localhost:5555/stage-api/user/list如果返回HTTP/1.1 200 OK和 JSON 数据说明代理链路完全通了。如果返回HTTP/1.1 404 Not Found把同样的路径直接打到后端地址试试curl -i http://192.168.17.11/stage-api/user/list如果后端直接访问也是 404那就是接口路径本身的问题跟代理无关。如果后端直接访问是 200但通过 live-server 是 404那就是baseUri和proxyUri的拼接规则没对上。4.3 验证模型接口的返回如果你调试的是模型对话类接口代理通了之后应该能看到流式返回。用 curl 测试时加-N参数禁用缓冲curl -N -X POST http://localhost:5555/stage-api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_KEY \ -d {model:gpt-4o-mini,messages:[{role:user,content:你好}],stream:true}如果能看到一行行data: {...}往外吐说明流式代理也正常。这里YOUR_KEY换成你在 TaoToken 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite拿到的 Key。注意model字段要填平台支持的模型 ID填错了会返回model not found。4.4 确认热更新是否工作live-server 的核心卖点之一是保存即刷新。你可以在dist目录下随便改一个 CSS 文件里的颜色值保存浏览器应该会自动刷新并显示新颜色。如果没刷新检查wait是不是设得太长或者ignoreFiles里是不是把 CSS 排除掉了。默认配置下dist里的静态文件变更都会触发刷新。不过要注意dist是打包产物你改dist里的文件只是临时验证真正的修改应该回到源码工程重新 build。live-server 在这里的作用是让你快速验证打包结果而不是替代构建流程。5. 常见报错对照排查401、proxy failed、choices 读取失败5.1 401 Unauthorized这是鉴权失败不是跨域问题。跨域问题的报错关键词是CORS、Access-Control-Allow-Origin而 401 说明请求已经到达后端只是凭证不对。排查顺序先看请求头里有没有Authorization再看 Key 是不是过期或者复制时多了空格。如果你用的是 TaoToken 的 Key到 API Keys 页面确认一下这个 Key 的状态是否正常。还有一种情况是代理把 header 吃掉了。live-server 的代理默认会转发大部分 header但如果你在settings.json里配了额外的headers字段覆盖可能会把Authorization冲掉。检查配置里有没有多余的 header 设置。5.2 local proxy failed / ECONNREFUSED这个报错说明 live-server 无法连接到proxyUri。可能原因有三个后端服务没启动、IP 写错了、端口被防火墙挡了。先用ping确认 IP 可达再用telnet 192.168.17.11 80确认端口通。如果后端在本机proxyUri写http://127.0.0.1:8080比写局域网 IP 更稳。还有一种隐蔽情况proxyUri结尾多了斜杠。比如写成http://192.168.17.11/stage-api/而baseUri是/stage-api拼接后可能变成/stage-api//user/list双斜杠有些后端会 404。统一去掉结尾斜杠。5.3 reading choices 报错这个报错通常出现在模型接口调试中完整信息类似Cannot read properties of undefined (reading choices)。意思是前端代码期望响应体里有choices字段但实际返回的结构不是标准格式。原因可能是接口返回了错误对象比如{error: {message: ...}}但前端没做错误分支直接去读choices就崩了。排查方法在 Network 面板里看这条请求的 Response 原文。如果是错误对象先解决错误如果返回的是流式数据前端解析方式要和流式格式匹配不能按普通 JSON 解析。用 TaoToken 的模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite可以先手动验证一下模型和 Key 是否可用排除掉服务端问题。5.4 OAuth / 登录态相关报错如果你的 dist 包依赖登录态本地调试时可能会遇到 OAuth 回调地址不匹配的问题。因为 OAuth 提供商通常校验redirect_uri而localhost:5555可能不在白名单里。解决办法是在 OAuth 应用配置里把http://localhost:5555/callback加进允许列表。如果改不了就用测试环境的账号体系或者让后端提供一个免登录的调试 Token。5.5 配置不生效的通用排查如果改完settings.json什么都没变化按这个顺序查第一确认文件在.vscode/settings.json而不是用户级 settings第二确认 JSON 语法正确多余的逗号会导致整个文件被忽略第三确认 live-server 已重启第四看 VS Code 的 Output 面板选择 live-server 通道里面会打印实际的代理配置和转发日志这是最直接的证据。6. 把本地调试链路接到真实接口上dist 包跑起来、代理配好、请求能通这条链路本身已经完整了。但很多时候你调试的接口需要真实数据尤其是模型类、AI 类接口本地 mock 很难模拟出真实返回。这时候需要一个稳定的接口来源。TaoToken 在这里的角色是提供兼容 OpenAI 格式的接口端点。你不需要改前端代码的请求结构只需要把proxyUri指向它的 API 地址或者在请求头里带上它签发的 Key。接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里有完整的端点说明和参数示例对着改proxyUri就行。如果你调试的是 Claude Code 这类编码 Agent 的本地链路配置方式略有不同需要设置 Base URL、Key 和 Model ID 三件套。Base URL 填https://taotoken.net/apiKey 用控制台签发的Model ID 按文档里支持的填。这三项在 Claude Code 的配置文件里对应不同的字段名具体可以看 ClaudeCodeAnthropic 的接入说明https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite。对于需要长期跑编码任务、Agent 调用的场景反复手动配 Key 比较麻烦可以用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite来管理额度省去每次调试都要换 Key 的步骤。回到 live-server 本身最后提醒一个实操细节dist目录每次重新 build 都会被覆盖但.vscode/settings.json如果放在dist里面build 时可能被清掉。稳妥的做法是把.vscode放在dist的上一级然后每次打开dist时手动把配置复制过去或者用符号链接。我自己的习惯是在源码工程里维护一份settings.json模板build 脚本里加一行把它复制到dist/.vscode/这样每次打包完配置都在点 Go Live 就能直接跑。