---
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/
```

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