Dai0814
22a177c569
原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页： - 概览（含选型指引与环境对照表） - 路径前缀必读（独立成页，最高频故障） - 推荐环境：Docker + nginx - 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm） - 内网与离线部署（4 种方案 + 对比表） - 本地开发与预览（含新增页面步骤） - 常见问题（部署/构建/运行三类 + 自检清单） 侧边栏分为三组：部署手册 / 部署方式 / 开发与排错
178 lines
4.1 KiB
Markdown
178 lines
4.1 KiB
Markdown
---
|
||
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/
|
||
```
|
||
|
||
四项都正常才算部署成功。浏览器再打开一次确认没有白屏。
|