---
title: 路径前缀必读
description: base=/docs/ 导致的部署白屏问题与三种正确做法
outline: deep
---

# 路径前缀必读

这是本项目最容易出错的地方，**部署失败九成是这个原因**。部署前请务必读完本页。

## 问题成因

文档站配置里 `base: '/docs/'`（见 `.vitepress/config.mts`），因此构建产物中所有资源引用都是**绝对路径**：

```html
<link rel="stylesheet" href="/docs/assets/style.xxx.css">
<script src="/docs/assets/app.xxx.js"></script>
```

而产物目录 `.vitepress/dist` 是**平铺**的，`index.html`、`assets/` 直接在根，**没有 `docs/` 子目录**。

由此推出两条铁律：

1. **对外访问路径必须是 `/docs/`**，且服务器必须把 `/docs/` 前缀剥掉后再落到产物目录
2. 若想挂到别的前缀（如 `/manual/`），必须**先改 `base` 再重新构建**，不能只改服务器配置

::: warning 典型故障：白屏
如果配置成「从根路径直接服务产物」（`root` 指向 dist，访问 `/`），页面 HTML 会返回 200，但 `/docs/assets/*.js` 全部 404 → **浏览器白屏，没有任何报错提示**。

这种情况最坑的地方是：`curl /` 返回 200，看起来部署成功了，实际打开浏览器是空白页。
:::

## 三种正确做法

| 做法 | 适用 | 关键配置 |
| --- | --- | --- |
| nginx `alias` 剥前缀 | 容器部署（推荐） | `location /docs/ { alias /usr/share/nginx/html/; }` |
| 把产物放进 `docs/` 子目录 | 静态托管 / 对象存储 | `dist/` → `www/docs/` |
| 改 `base: '/'` 重新构建 | 独占域名根路径 | 改配置后必须重新 `npm run build` |

### 做法一：nginx alias 剥前缀

```nginx
location /docs/ {
    alias /usr/share/nginx/html/;
    try_files $uri $uri.html $uri/ $uri/index.html =404;
}
```

`alias` 会剥掉 `location` 的前缀，`/docs/assets/app.js` 实际读到 `/usr/share/nginx/html/assets/app.js`，正好对上平铺的产物目录。

详见 [推荐环境部署：Docker + nginx](./docker-nginx)。

### 做法二：产物放进 docs 子目录

```bash
sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
```

```nginx
root /var/www/iotlcm/www;
location /docs/ {
    try_files $uri $uri.html $uri/ $uri/index.html =404;
}
```

`/docs/assets/app.js` 自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。

详见 [静态托管部署](./static-hosting)。

### 做法三：改 base 重新构建

```bash
sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
npm run build
```

仅适用于文档站独占域名根路径的场景。

::: danger 不要只改服务器配置
`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。
:::

## cleanUrls 的额外要求

配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀（如 `/manual/web/` 而非 `/manual/web.html`）。

因此服务器的 `try_files` **必须**包含 `$uri.html` 与 `$uri/index.html` 映射：

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

缺了这两项的表现是：首页正常，但点进任何内页都是 404。

对象存储场景下需确认支持「无后缀映射到 `.html`」，否则要关闭 `cleanUrls` 重新构建。