问题记录

问题记录模块用于沉淀开发、构建、部署和线上排查过程中遇到的典型问题。每条记录建议保留现象、原因、解决方案和预防措施，方便后续复盘和快速定位。

记录模板

## 问题标题

### 现象

描述用户或开发者看到的错误表现，例如报错信息、页面状态、接口响应、构建日志。

### 环境

- 系统：
- Node 版本：
- 包管理器：
- 框架版本：
- 触发命令：

### 原因

说明根因，不只记录临时解决命令。

### 解决方案

给出可执行步骤，必要时附代码或命令。

### 预防措施

说明如何避免再次发生，例如锁版本、补测试、增加文档、调整 CI。

常见问题分类

依赖安装

• node_modules 与锁文件不一致导致本地构建失败。
• Node 版本过低或过高导致脚手架、构建工具不可用。
• npm、pnpm、yarn 混用导致依赖解析异常。

建议处理：

node -v
npm -v
npm ci

如果项目使用 pnpm 或 yarn，应统一团队命令和锁文件，避免同时提交多个 lock 文件。

VitePress 构建

常见现象：

• Markdown 链接路径错误。
• 组件只能在客户端运行，却在构建阶段访问了 window 或 document。
• 静态资源路径不正确，部署后图片或动画 404。

排查顺序：

1. 运行 npm run docs:build 查看完整报错。
2. 检查链接是否以文档站根路径为基准。
3. 检查资源是否放在 docs/public 下。
4. 对浏览器专属逻辑使用 onMounted 或动态导入。

中文乱码

常见原因：

• 文件编码不是 UTF-8。
• 终端编码和文件编码不一致。
• 复制内容时被错误转码。

建议处理：

• Markdown、JavaScript、Vue 文件统一保存为 UTF-8。
• Windows PowerShell 查看中文时可先执行：

chcp 65001

• 如果文件内容已经被保存成乱码，需要从历史版本恢复或重新整理原文。

部署路径

VitePress 部署到子路径时，需要配置 base。例如站点部署到 /docs/：

export default defineConfig({
  base: "/docs/"
})

同时检查图片、链接、导航和站内跳转是否都能在该子路径下访问。

排查原则

• 先复现，再修改。
• 先看第一条有效报错，不要被后续连锁错误带偏。
• 修改依赖版本后必须重新安装并构建。
• 配置类问题要补文档，避免只靠口头记忆。
• 线上问题处理完后补充监控、日志或自动化检查。