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

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

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

docs/deploy/faq.md

@@ -0,0 +1,177 @@
+---
+title: 常见问题
+description: 部署与构建过程中的故障排查
+outline: deep
+---
+
+# 常见问题
+
+## 部署类
+
+### 页面能打开但白屏、无样式
+
+**原因**：`/docs/` 路径前缀未剥离，资源全部 404。
+
+这是最常见的部署故障。`base: '/docs/'` 使 HTML 引用 `/docs/assets/*`，但产物是平铺的，服务器从根路径找 `/assets/*` 就 404。
+
+**危险之处**：`curl /` 返回 200，看起来部署成功，实际浏览器是空白。
+
+**处理**：见 [路径前缀必读](./path-prefix)，三种做法任选其一。
+
+### 访问 `/` 返回 404
+
+**原因**：`base: '/docs/'`，站点根路径不是入口。
+
+**处理**：访问 `/docs/`。若希望 `/` 自动跳转，加：
+
+```nginx
+location = / { return 302 /docs/; }
+```
+
+### 访问 `/docs`（无末尾斜杠）404
+
+**原因**：未配置重定向，而 VitePress 生成的目录结构需要末尾斜杠。
+
+**处理**：
+
+```nginx
+location = /docs { return 301 /docs/; }
+```
+
+### 首页正常，点进任何内页都 404
+
+**原因**：`cleanUrls: true` 使页面 URL 不带 `.html`，服务器缺少内部映射。
+
+**处理**：`try_files` 补上两种映射：
+
+```nginx
+try_files $uri $uri.html $uri/ $uri/index.html =404;
+```
+
+### 反向代理后白屏
+
+**原因**：`proxy_pass` 带了末尾斜杠，把 `/docs/` 前缀剥掉后转发成 `/`。
+
+**处理**：去掉末尾斜杠：
+
+```nginx
+# 错误
+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` 不同步。
+
+**处理**：
+
+1. 升级到 Node 22：
+
+   ```bash
+   node -v   # 确认 >= 18，推荐 22
+   ```
+
+2. 若仍失败，改用 `npm install`（会更新 lock，注意提交变更）：
+
+   ```bash
+   npm install
+   ```
+
+### 构建报内存不足
+
+**原因**：构建峰值约 500 MB，容器内存限制过小时 OOM。
+
+**处理**：给到 ≥ 1 GB：
+
+```bash
+docker run -m 1g ...
+```
+
+或临时提高 Node 堆上限：
+
+```bash
+NODE_OPTIONS=--max-old-space-size=2048 npm run build
+```
+
+### 构建成功但页面内容缺失
+
+**原因**：`.md` 文件未保存、或文件不在 `docs/`（`srcDir`）目录下。
+
+**处理**：确认文件路径在 `docs/` 下，且已在 `.vitepress/config.mts` 的 sidebar 注册。
+
+### 新增页面左侧目录不显示
+
+**原因**：只在 `docs/` 下建了文件，没在 `sidebar` 配置里注册。
+
+**处理**：见 [本地开发与预览](./local-dev) 的「新增页面的步骤」。
+
+### 中文搜索失效或搜不到新页面
+
+**原因**：本地搜索索引在构建时生成，dev 模式下可能有延迟；产物未重新构建。
+
+**处理**：重新 `npm run build`。
+
+## 运行类
+
+### 端口 5173 被占用
+
+**处理**：
+
+```bash
+npx vitepress dev . --port 5174
+```
+
+或结束旧进程：
+
+```bash
+lsof -ti:5173 | xargs kill
+```
+
+### 局域网其他机器访问不了 dev 服务
+
+**原因**：默认只监听 `127.0.0.1`。
+
+**处理**：
+
+```bash
+npx vitepress dev . --host 0.0.0.0
+```
+
+并确认防火墙放行对应端口。
+
+### 修改 `.md` 后页面没更新
+
+**原因**：浏览器缓存，或 dev 进程已退出。
+
+**处理**：硬刷新（`Ctrl+Shift+R`），确认终端里 dev 进程仍在运行。
+
+## 快速自检清单
+
+部署完成后依次确认：
+
+```bash
+# 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/
+```
+
+四项都正常才算部署成功。浏览器再打开一次确认没有白屏。