Files

T

Dai0814 22a177c569 docs: 部署手册拆分为多页，左侧形成三层目录

原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页：
- 概览（含选型指引与环境对照表）
- 路径前缀必读（独立成页，最高频故障）
- 推荐环境：Docker + nginx
- 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm）
- 内网与离线部署（4 种方案 + 对比表）
- 本地开发与预览（含新增页面步骤）
- 常见问题（部署/构建/运行三类 + 自检清单）

侧边栏分为三组：部署手册 / 部署方式 / 开发与排错

2026-10-26 17:12:18 +08:00

4.1 KiB

Raw Blame History

title, description, outline

title	description	outline
常见问题	部署与构建过程中的故障排查	deep

常见问题

部署类

页面能打开但白屏、无样式

原因：/docs/ 路径前缀未剥离，资源全部 404。

这是最常见的部署故障。base: '/docs/' 使 HTML 引用 /docs/assets/*，但产物是平铺的，服务器从根路径找 /assets/* 就 404。

危险之处：curl / 返回 200，看起来部署成功，实际浏览器是空白。

处理：见路径前缀必读，三种做法任选其一。

访问 `/` 返回 404

原因：base: '/docs/'，站点根路径不是入口。

处理：访问 /docs/。若希望 / 自动跳转，加：

location = / { return 302 /docs/; }

访问 `/docs`（无末尾斜杠）404

原因：未配置重定向，而 VitePress 生成的目录结构需要末尾斜杠。

处理：

location = /docs { return 301 /docs/; }

首页正常，点进任何内页都 404

原因：cleanUrls: true 使页面 URL 不带 .html，服务器缺少内部映射。

处理：try_files 补上两种映射：

try_files $uri $uri.html $uri/ $uri/index.html =404;

反向代理后白屏

原因：proxy_pass 带了末尾斜杠，把 /docs/ 前缀剥掉后转发成 /。

处理：去掉末尾斜杠：

# 错误
proxy_pass http://iotlcm_docs/;
# 正确
proxy_pass http://iotlcm_docs;

图片全部 404

原因：图片放在 docs/public/images/，构建后映射到产物根的 images/，引用时需要用站点绝对路径（含 base）。

处理：正文写 /images/xxx.png（VitePress 会自动补 base）。若写相对路径 ./images/xxx.png 会因页面层级不同而失效。

构建类

`npm ci` 报 lock 文件不一致

原因：Node 版本过低，或 lock 与 package.json 不同步。

处理：

升级到 Node 22：
```
node -v   # 确认 >= 18，推荐 22
```
若仍失败，改用 npm install（会更新 lock，注意提交变更）：
```
npm install
```

构建报内存不足

原因：构建峰值约 500 MB，容器内存限制过小时 OOM。

处理：给到 ≥ 1 GB：

docker run -m 1g ...

或临时提高 Node 堆上限：

NODE_OPTIONS=--max-old-space-size=2048 npm run build

构建成功但页面内容缺失

原因：.md 文件未保存、或文件不在 docs/（srcDir）目录下。

处理：确认文件路径在 docs/ 下，且已在 .vitepress/config.mts 的 sidebar 注册。

新增页面左侧目录不显示

原因：只在 docs/ 下建了文件，没在 sidebar 配置里注册。

处理：见本地开发与预览的「新增页面的步骤」。

中文搜索失效或搜不到新页面

原因：本地搜索索引在构建时生成，dev 模式下可能有延迟；产物未重新构建。

处理：重新 npm run build。

运行类

端口 5173 被占用

处理：

npx vitepress dev . --port 5174

或结束旧进程：

lsof -ti:5173 | xargs kill

局域网其他机器访问不了 dev 服务

原因：默认只监听 127.0.0.1。

处理：

npx vitepress dev . --host 0.0.0.0

并确认防火墙放行对应端口。

修改 `.md` 后页面没更新

原因：浏览器缓存，或 dev 进程已退出。

处理：硬刷新（Ctrl+Shift+R），确认终端里 dev 进程仍在运行。

快速自检清单

部署完成后依次确认：

# 1. 入口 200
curl -o /dev/null -s -w '%{http_code}\n' http://<host>/docs/

# 2. 根路径 302（若配置了重定向）
curl -o /dev/null -s -w '%{http_code}\n' http://<host>/

# 3. 静态资源 200（最关键）
ASSET=$(curl -s http://<host>/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
curl -o /dev/null -s -w '%{http_code}\n' "http://<host>$ASSET"

# 4. 内页 200
curl -o /dev/null -s -w '%{http_code}\n' http://<host>/docs/manual/web/

四项都正常才算部署成功。浏览器再打开一次确认没有白屏。

4.1 KiB Raw Blame History Unescape Escape