7.2 常见问题与排错

从控制台第一条错误开始，先确认文件、项目目录和访问地址。后续错误可能只是第一条失败的连锁结果。

状态变了，页面没变

检查项	修正方向
使用了普通 let	改为 ref/reactive
脚本忘记 .value	访问 ref.value
reactive 原始字段被直接解构	用 toRefs 或保持对象访问
Pinia state 被直接解构	用 storeToRefs
对 DOM 尺寸观察太早	等 nextTick
状态属于另一组件实例	核对数据创建与共享位置

不要为了让数字更新，手工操作 DOM 或强制刷新整个页面。先找状态追踪哪里断开了。

列表输入错位

插入或排序后任务行的输入框显示错误，优先检查 :key 是否使用数组下标、重复值或每次渲染新生成的随机值。业务 ID 稳定且唯一，适合作为 key。

v-for 与 v-if 放在同一个元素会有优先级问题。改为 computed 先筛选。

页面提交后刷新

表单缺少 @submit.prevent，或表单内部普通按钮未写 type="button"。Enter 提交也走 form 的 submit 事件，不必只监听按钮 click。

导入模块报错

检查具名导入是否带花括号、默认导出是否被误当具名导出、文件路径是否相对当前文件。Windows 大小写不敏感可能掩盖路径错误，Linux 部署时会暴露。

Vue - Official 能帮助编辑器理解 .vue；文档站本身是 React/MDX，不能直接当 Vue 项目启动。

fetch 的 catch 没收到 500

这是预期行为。HTTP 响应已经到达，必须检查 response.ok。catch 接收网络失败、手动抛出的错误以及 JSON 解析失败。

若出现 Unexpected token '<'，查看响应正文是不是 HTML。常见原因是路径错误、代理没生效或被前端回退到 index.html。

删除后 JSON 解析失败

DELETE 返回 204 时没有正文。成功后直接更新本地列表，不调用 response.json()。详见HTTP 请求。

Swagger 成功，Vue 失败

现象	原因方向
OPTIONS 返回错误	CORS 预检
localhost 的请求去了错误端口	代理 target 或启动端口
401	凭据没发送、过期或认证配置
403	授权规则，不一定是登录失效
字段全是 undefined	JSON 字段名或统一包装未对齐

浏览器和 API 文档工具的执行环境不同。结合CORS 与代理排查。

开发正常，部署后异常

Vue SPA 刷新详情路径 404，需要前端路径回退。静态资源 404，需要核对 Vite base；Docusaurus 子目录部署需要在构建前设置 baseUrl。

生产服务器没有 Vite 开发代理，要配置 /api 反向代理或后端 CORS。环境变量改后没有重新构建，前端产物仍可能指向旧 API。

文档搜索没有结果

中文本地搜索索引在生产构建时生成。先执行 npm run build，再用 npm run serve 检查；开发模式不作为搜索索引的最终验收环境。新文章也需要重新构建索引。

如果搜索索引请求 404，检查部署是否上传完整 build、子目录 baseUrl 是否匹配，以及缓存是否保留旧索引文件名。

如何提出可定位的问题

记录：项目与文件位置、触发操作、预期与实际表现、控制台第一条错误、请求 URL 和状态码、响应正文。再提供最小相关片段，移除密码和 token。

练习： 故意把请求路径改为不存在的地址，在 Network 里解释为什么页面报错；恢复路径后验证恢复。不要仅凭某段 Console 输出猜测服务器行为。