Files

T

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

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

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

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

3.2 KiB

Raw Blame History

title, description, outline

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

路径前缀必读

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

问题成因

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

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

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

由此推出两条铁律：

对外访问路径必须是 /docs/，且服务器必须把 /docs/ 前缀剥掉后再落到产物目录
若想挂到别的前缀（如 /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 剥前缀

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。

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

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

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。

详见静态托管部署。

做法三：改 base 重新构建

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 映射：

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

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

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

3.2 KiB Raw Blame History Unescape Escape