docs: 部署手册拆分为多页，左侧形成三层目录
原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页： - 概览（含选型指引与环境对照表） - 路径前缀必读（独立成页，最高频故障） - 推荐环境：Docker + nginx - 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm） - 内网与离线部署（4 种方案 + 对比表） - 本地开发与预览（含新增页面步骤） - 常见问题（部署/构建/运行三类 + 自检清单） 侧边栏分为三组：部署手册 / 部署方式 / 开发与排错
This commit is contained in:
Dai0814
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Docker + nginx 部署
|
||||
description: 推荐环境部署方式：多阶段构建镜像 + nginx 托管
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 推荐环境部署：Docker + nginx
|
||||
|
||||
适用：生产环境、需要长期稳定运行、机器上不想装 Node。
|
||||
|
||||
仓库自带多阶段 `Dockerfile`：Node 阶段执行 `vitepress build`，最终镜像只含 nginx 与静态产物，**不含 Node 和 `node_modules`**。
|
||||
|
||||
## 构建镜像
|
||||
|
||||
```bash
|
||||
SHA=$(git rev-parse --short HEAD)
|
||||
docker build -t iotlcm-docs:$SHA .
|
||||
```
|
||||
|
||||
用 commit sha 做标签，便于追溯与回滚；不建议只用 `latest`。
|
||||
|
||||
## 启动容器
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name iotlcm-docs \
|
||||
--restart unless-stopped \
|
||||
-p 8019:80 \
|
||||
iotlcm-docs:$SHA
|
||||
```
|
||||
|
||||
## nginx 配置（关键）
|
||||
|
||||
`docker/nginx.conf` 用 `alias` 把 `/docs/` 前缀剥掉：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name _;
|
||||
|
||||
root /usr/share/nginx/html;
|
||||
index index.html;
|
||||
|
||||
# 产物按 base=/docs/ 生成，资源引用形如 /docs/assets/xxx
|
||||
location /docs/ {
|
||||
alias /usr/share/nginx/html/;
|
||||
try_files $uri $uri.html $uri/ $uri/index.html =404;
|
||||
}
|
||||
|
||||
# 根路径跳到文档入口，避免访问 / 时白屏
|
||||
location = / {
|
||||
return 302 /docs/;
|
||||
}
|
||||
|
||||
location / {
|
||||
try_files $uri $uri.html $uri/ =404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`try_files` 里的 `$uri.html` 与 `$uri/index.html` 是必需的：配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀，需要服务器做内部映射。
|
||||
|
||||
原理说明见 [路径前缀必读](./path-prefix)。
|
||||
|
||||
## 部署后自检
|
||||
|
||||
```bash
|
||||
# 1. 入口可访问（应返回 200）
|
||||
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/
|
||||
|
||||
# 2. 根路径应 302 到 /docs/
|
||||
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/
|
||||
|
||||
# 3. 静态资源不能 404（最容易出问题的一步）
|
||||
ASSET=$(curl -s http://127.0.0.1:8019/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
|
||||
curl -o /dev/null -s -w '%{http_code}\n' "http://127.0.0.1:8019$ASSET"
|
||||
|
||||
# 4. 抽查正文页面
|
||||
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/manual/web/
|
||||
```
|
||||
|
||||
四项都返回 `200`（第 2 项返回 `302`）才算部署成功。
|
||||
|
||||
## 通过外层反向代理对外
|
||||
|
||||
生产常见做法：容器只监听 `127.0.0.1`，由外层 nginx 转发。
|
||||
|
||||
```nginx
|
||||
upstream iotlcm_docs {
|
||||
server 127.0.0.1:8019;
|
||||
}
|
||||
|
||||
location = /docs {
|
||||
return 301 /docs/;
|
||||
}
|
||||
|
||||
location /docs/ {
|
||||
proxy_pass http://iotlcm_docs; # 末尾不要加斜杠
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
```
|
||||
|
||||
::: danger proxy_pass 末尾斜杠
|
||||
写成 `proxy_pass http://iotlcm_docs/;`（带末尾斜杠）会把 `/docs/` 前缀剥掉，转发到容器变成 `/`，导致资源全部 404 白屏。**必须不带末尾斜杠**。
|
||||
:::
|
||||
|
||||
## docker compose
|
||||
|
||||
`docker-compose.yml` 中镜像名是占位值，需替换为自己的仓库地址：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
docs:
|
||||
image: your-registry/iotlcm/iotlcm-docs:${TAG:-latest}
|
||||
container_name: iotlcm-docs
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:8019:80"
|
||||
networks:
|
||||
- iotlcm-network
|
||||
|
||||
networks:
|
||||
iotlcm-network:
|
||||
external: true
|
||||
name: iotlcm-network
|
||||
```
|
||||
|
||||
compose 文件声明 `iotlcm-network` 为外部网络，若不存在需先创建：
|
||||
|
||||
```bash
|
||||
docker network create iotlcm-network
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
TAG=$(git rev-parse --short HEAD) docker compose up -d
|
||||
```
|
||||
|
||||
## 版本固定与升级
|
||||
|
||||
开源仓按**固定版本**发布（无 git 历史，单次初始提交）。部署时请记录并锁定 commit：
|
||||
|
||||
```bash
|
||||
SHA=$(git rev-parse HEAD)
|
||||
echo "部署基线: $SHA" >> deploy.log
|
||||
docker build -t iotlcm-docs:$SHA .
|
||||
```
|
||||
|
||||
升级文档时，从上游选定基线重新发布后，按新 sha 重建镜像并滚动替换容器：
|
||||
|
||||
```bash
|
||||
docker rm -f iotlcm-docs
|
||||
docker run -d --name iotlcm-docs --restart unless-stopped -p 8019:80 iotlcm-docs:$NEW_SHA
|
||||
```
|
||||
@@ -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/
|
||||
```
|
||||
|
||||
四项都正常才算部署成功。浏览器再打开一次确认没有白屏。
|
||||
+27
-388
@@ -1,17 +1,27 @@
|
||||
---
|
||||
title: 部署手册
|
||||
description: iotLCM 文档站的推荐环境、编译方法与部署方式
|
||||
title: 部署概览
|
||||
description: iotLCM 文档站的部署方式总览与环境要求
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 部署手册
|
||||
# 部署概览
|
||||
|
||||
本页说明 iotLCM 文档站（`iotlcm-docs`）的运行环境要求、编译方法与部署方式。文档站是**纯静态站点**，由 VitePress 1.6 构建，产物不含任何服务端运行时。
|
||||
本手册说明 iotLCM 文档站（`iotlcm-docs`）的环境要求、编译方法与部署方式。文档站是**纯静态站点**，由 VitePress 1.6 构建，产物不含任何服务端运行时。
|
||||
|
||||
::: tip 一句话结论
|
||||
生产推荐用 **Docker + nginx**（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 **Node 构建 + 任意 Web 服务器托管静态产物**。
|
||||
生产推荐 **Docker + nginx**（Node 只在构建阶段需要）；只有一台机器、不想装 Docker 时，用 **Node 构建 + 任意 Web 服务器托管静态产物**。
|
||||
:::
|
||||
|
||||
## 怎么选部署方式
|
||||
|
||||
| 你的情况 | 看哪页 |
|
||||
| --- | --- |
|
||||
| 生产环境，机器上不想装 Node | [推荐环境部署：Docker + nginx](./docker-nginx) |
|
||||
| 有现成 nginx，只需托管静态文件 | [静态托管部署](./static-hosting) |
|
||||
| 内网 / 无法访问公网 npm | [内网与离线部署](./offline) |
|
||||
| 只是改文档、本地看效果 | [本地开发与预览](./local-dev) |
|
||||
| 遇到报错或白屏 | [常见问题](./faq) |
|
||||
|
||||
## 环境要求
|
||||
|
||||
### 构建环境（必需）
|
||||
@@ -35,7 +45,9 @@ outline: deep
|
||||
| 容器运行时 | Docker 20+ / Docker Compose v2 | 仅容器方式需要 |
|
||||
| 资源占用 | 内存 32 MB、磁盘 30 MB | 纯静态，压力极低 |
|
||||
|
||||
### 实测参考（Debian/Ubuntu + Node 22 + Docker 29）
|
||||
### 实测参考
|
||||
|
||||
在 Debian/Ubuntu + Node 22 + Docker 29 上实测：
|
||||
|
||||
| 操作 | 耗时 | 产物 |
|
||||
| --- | --- | --- |
|
||||
@@ -52,392 +64,19 @@ git clone https://git.5iot.com/iotlcm-public/iotlcm-docs.git
|
||||
cd iotlcm-docs
|
||||
```
|
||||
|
||||
开源仓**不含 git 历史**，只有一个初始提交，这是预期行为：
|
||||
开源仓**不含 git 历史**，从初始提交开始累积：
|
||||
|
||||
```bash
|
||||
git log --oneline
|
||||
# 92f239f chore: 初始开源发布
|
||||
```
|
||||
|
||||
## ⚠️ 部署前必读：路径前缀
|
||||
|
||||
这是本项目最容易出错的地方，**部署失败九成是这个原因**。
|
||||
|
||||
文档站配置里 `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 → **浏览器白屏，没有任何报错提示**。
|
||||
:::
|
||||
|
||||
三种正确做法，任选其一：
|
||||
|
||||
| 做法 | 适用 | 关键配置 |
|
||||
| --- | --- | --- |
|
||||
| nginx `alias` 剥前缀 | 容器部署（推荐） | `location /docs/ { alias /usr/share/nginx/html/; }` |
|
||||
| 把产物放进 `docs/` 子目录 | 静态托管 / 对象存储 | `dist/` → `www/docs/` |
|
||||
| 改 `base: '/'` 重新构建 | 独占域名根路径 | 改配置后必须重新 `npm run build` |
|
||||
|
||||
---
|
||||
|
||||
## 推荐环境部署：Docker + nginx
|
||||
|
||||
适用：生产环境、需要长期稳定运行、机器上不想装 Node。
|
||||
|
||||
仓库自带多阶段 `Dockerfile`：Node 阶段执行 `vitepress build`，最终镜像只含 nginx 与静态产物，**不含 Node 和 `node_modules`**。
|
||||
|
||||
### 构建镜像
|
||||
|
||||
```bash
|
||||
SHA=$(git rev-parse --short HEAD)
|
||||
docker build -t iotlcm-docs:$SHA .
|
||||
```
|
||||
|
||||
用 commit sha 做标签，便于追溯与回滚；不建议只用 `latest`。
|
||||
|
||||
### 启动容器
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name iotlcm-docs \
|
||||
--restart unless-stopped \
|
||||
-p 8019:80 \
|
||||
iotlcm-docs:$SHA
|
||||
```
|
||||
|
||||
### nginx 配置（关键）
|
||||
|
||||
`docker/nginx.conf` 用 `alias` 把 `/docs/` 前缀剥掉：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name _;
|
||||
|
||||
root /usr/share/nginx/html;
|
||||
index index.html;
|
||||
|
||||
# 产物按 base=/docs/ 生成，资源引用形如 /docs/assets/xxx
|
||||
location /docs/ {
|
||||
alias /usr/share/nginx/html/;
|
||||
try_files $uri $uri.html $uri/ $uri/index.html =404;
|
||||
}
|
||||
|
||||
# 根路径跳到文档入口，避免访问 / 时白屏
|
||||
location = / {
|
||||
return 302 /docs/;
|
||||
}
|
||||
|
||||
location / {
|
||||
try_files $uri $uri.html $uri/ =404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`try_files` 里的 `$uri.html` 与 `$uri/index.html` 是必需的：配置启用了 `cleanUrls: true`，页面 URL 不带 `.html` 后缀，需要服务器做内部映射。
|
||||
|
||||
### 部署后自检
|
||||
|
||||
```bash
|
||||
# 1. 入口可访问（应返回 200）
|
||||
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/
|
||||
|
||||
# 2. 根路径应 302 到 /docs/
|
||||
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/
|
||||
|
||||
# 3. 静态资源不能 404（最容易出问题的一步）
|
||||
ASSET=$(curl -s http://127.0.0.1:8019/docs/ | grep -o '/docs/assets/style[^"]*\.css' | head -1)
|
||||
curl -o /dev/null -s -w '%{http_code}\n' "http://127.0.0.1:8019$ASSET"
|
||||
|
||||
# 4. 抽查正文页面
|
||||
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1:8019/docs/manual/web/
|
||||
```
|
||||
|
||||
四项都返回 `200`（第 2 项返回 `302`）才算部署成功。
|
||||
|
||||
### 通过外层反向代理对外
|
||||
|
||||
生产常见做法：容器只监听 `127.0.0.1`，由外层 nginx 转发。
|
||||
|
||||
```nginx
|
||||
upstream iotlcm_docs {
|
||||
server 127.0.0.1:8019;
|
||||
}
|
||||
|
||||
location = /docs {
|
||||
return 301 /docs/;
|
||||
}
|
||||
|
||||
location /docs/ {
|
||||
proxy_pass http://iotlcm_docs; # 末尾不要加斜杠
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
```
|
||||
|
||||
::: danger proxy_pass 末尾斜杠
|
||||
写成 `proxy_pass http://iotlcm_docs/;`（带末尾斜杠）会把 `/docs/` 前缀剥掉，转发到容器变成 `/`，导致资源全部 404 白屏。**必须不带末尾斜杠**。
|
||||
:::
|
||||
|
||||
### docker compose
|
||||
|
||||
`docker-compose.yml` 中镜像名是占位值，需替换为自己的仓库地址：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
docs:
|
||||
image: your-registry/iotlcm/iotlcm-docs:${TAG:-latest}
|
||||
container_name: iotlcm-docs
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "127.0.0.1:8019:80"
|
||||
networks:
|
||||
- iotlcm-network
|
||||
|
||||
networks:
|
||||
iotlcm-network:
|
||||
external: true
|
||||
name: iotlcm-network
|
||||
```
|
||||
|
||||
compose 文件声明 `iotlcm-network` 为外部网络，若不存在需先创建：
|
||||
|
||||
```bash
|
||||
docker network create iotlcm-network
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
TAG=$(git rev-parse --short HEAD) docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 其他环境
|
||||
|
||||
### 方式一：本地开发与预览（改文档时用）
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
访问 **`http://127.0.0.1:5173/docs/`**。
|
||||
|
||||
::: warning 地址必须带 /docs/
|
||||
`base: '/docs/'` 决定了 dev 服务器入口也在子路径下，直接访问 `http://127.0.0.1:5173/` 会 404。
|
||||
:::
|
||||
|
||||
改动 `docs/` 下任意 `.md` 文件会热更新，无需重启。
|
||||
|
||||
需要让局域网内其他机器访问时，把监听地址改为 `0.0.0.0`：
|
||||
|
||||
```bash
|
||||
npx vitepress dev . --host 0.0.0.0
|
||||
# 然后访问 http://<本机IP>:5173/docs/
|
||||
```
|
||||
|
||||
端口被占用时换端口：
|
||||
|
||||
```bash
|
||||
npx vitepress dev . --port 5174
|
||||
```
|
||||
|
||||
### 方式二：构建静态产物 + 任意 Web 服务器
|
||||
|
||||
这是**不使用 Docker** 时最通用的做法。
|
||||
|
||||
#### 编译
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run build
|
||||
# 产物在 .vitepress/dist
|
||||
```
|
||||
|
||||
本地验证构建结果（不要用于生产）：
|
||||
|
||||
```bash
|
||||
npm run preview
|
||||
# http://127.0.0.1:4173/docs/
|
||||
```
|
||||
|
||||
#### 部署到 nginx（子路径挂载，推荐）
|
||||
|
||||
把产物放到一个 `docs` 子目录，即可与 `base` 天然对齐，**无需 alias**：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /var/www/iotlcm/www
|
||||
sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
|
||||
```
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name _;
|
||||
root /var/www/iotlcm/www;
|
||||
|
||||
location /docs/ {
|
||||
try_files $uri $uri.html $uri/ $uri/index.html =404;
|
||||
}
|
||||
|
||||
location = /docs {
|
||||
return 301 /docs/;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
此处 `root` 指向父目录、产物在 `docs/` 子目录下，`/docs/assets/app.js` 会自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
|
||||
|
||||
#### 部署到 nginx（根路径独占域名）
|
||||
|
||||
若文档站独占一个域名、需要挂在 `/`，必须**改 `base` 后重新构建**：
|
||||
|
||||
```bash
|
||||
sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
|
||||
npm run build
|
||||
```
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name docs.example.com;
|
||||
root /var/www/iotlcm-docs;
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri.html $uri/ =404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: danger 不要只改服务器配置
|
||||
`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。
|
||||
:::
|
||||
|
||||
#### 部署到对象存储 / CDN
|
||||
|
||||
产物是纯静态文件，可直接上传到 S3 / OSS / MinIO 等：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
# 上传 .vitepress/dist 全部内容到桶内 docs/ 前缀下
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- 上传时保持 `/docs/` 前缀（或改 `base` 后重新构建）
|
||||
- 配置**默认首页**为 `docs/index.html`
|
||||
- 配置 **404 页面**为 `docs/404.html`（产物已自带）
|
||||
- `cleanUrls: true` 意味着页面 URL 不带 `.html`，需对象存储支持「无后缀映射到 .html」，否则需关闭 `cleanUrls` 重新构建
|
||||
|
||||
### 方式三：内网 / 离线环境
|
||||
|
||||
机器无法访问公网 npm 源时：
|
||||
|
||||
**方案 A：使用内网镜像源**
|
||||
|
||||
```bash
|
||||
npm ci --registry=https://your-internal-registry/
|
||||
```
|
||||
|
||||
**方案 B：在有网机器构建后只拷产物**
|
||||
|
||||
产物是纯静态文件，**不需要在目标机器上装 Node**：
|
||||
|
||||
```bash
|
||||
# 有网机器
|
||||
npm ci && npm run build
|
||||
tar czf iotlcm-docs-dist.tar.gz -C .vitepress/dist .
|
||||
|
||||
# 目标机器
|
||||
tar xzf iotlcm-docs-dist.tar.gz -C /var/www/iotlcm/www/docs
|
||||
```
|
||||
|
||||
**方案 C：内网构建镜像**
|
||||
|
||||
`Dockerfile` 里基础镜像来自 Docker Hub（`node:22-alpine`、`nginx:1.27-alpine`），内网环境需先同步到内部镜像仓库，然后修改 `Dockerfile` 的 `FROM`：
|
||||
|
||||
```dockerfile
|
||||
FROM your-registry/library/node:22-alpine AS builder
|
||||
# ...
|
||||
FROM your-registry/library/nginx:1.27-alpine
|
||||
```
|
||||
|
||||
::: tip 已内置国内 apk 源
|
||||
`Dockerfile` 的 builder 阶段已把 Alpine 源换成 `mirrors.aliyun.com`，无需额外处理。
|
||||
:::
|
||||
|
||||
### 方式四：pnpm / yarn
|
||||
|
||||
仓库同时提供 `package-lock.json` 与 `pnpm-lock.yaml`。使用 pnpm：
|
||||
|
||||
```bash
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
npm 与 pnpm 二选一即可，**不要混用**（会产生不一致的 `node_modules`）。
|
||||
|
||||
---
|
||||
|
||||
## 环境对照表
|
||||
|
||||
| 场景 | Node | Docker | 访问路径 | 关键动作 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 本地改文档 | 必需 | 不需要 | `/docs/` | `npm run dev` |
|
||||
| 生产（推荐） | 仅构建阶段 | 必需 | `/docs/` | `docker build` + nginx alias |
|
||||
| 静态托管（子路径） | 仅构建阶段 | 不需要 | `/docs/` | 产物放 `docs/` 子目录 |
|
||||
| 静态托管（根路径） | 仅构建阶段 | 不需要 | `/` | 改 `base: '/'` 重新构建 |
|
||||
| 对象存储 / CDN | 仅构建阶段 | 不需要 | `/docs/` | 上传 + 配 404 与默认首页 |
|
||||
| 内网离线 | 可在别处构建 | 可选 | `/docs/` | 只拷产物或改 FROM |
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 原因 | 处理 |
|
||||
| --- | --- | --- |
|
||||
| 页面白屏、无样式 | `/docs/` 前缀未剥离，资源 404 | 用 `alias`，或产物放 `docs/` 子目录 |
|
||||
| 访问 `/` 404 | `base: '/docs/'` | 访问 `/docs/`；容器版已自动 302 |
|
||||
| 访问 `/docs`（无末尾斜杠）404 | 未配置重定向 | 加 `location = /docs { return 301 /docs/; }` |
|
||||
| 正文页 404、首页正常 | 缺 `$uri.html` 映射 | `try_files` 补 `$uri.html $uri/index.html` |
|
||||
| `npm ci` 报 lock 不一致 | Node 版本过低 | 升级到 Node 22 |
|
||||
| 构建报内存不足 | 容器内存限制过小 | 给到 ≥ 1 GB |
|
||||
| 端口 5173 被占用 | 已有 dev 进程在跑 | `--port 5174` 或结束旧进程 |
|
||||
| 反向代理后白屏 | `proxy_pass` 带了末尾斜杠 | 去掉末尾斜杠 |
|
||||
|
||||
## 版本固定
|
||||
|
||||
开源仓按**固定版本**发布（无 git 历史，单次初始提交）。部署时请记录并锁定 commit：
|
||||
|
||||
```bash
|
||||
SHA=$(git rev-parse HEAD)
|
||||
echo "部署基线: $SHA" >> deploy.log
|
||||
docker build -t iotlcm-docs:$SHA .
|
||||
```
|
||||
|
||||
升级文档时，从上游选定基线重新发布后，按新 sha 重建镜像并滚动替换容器：
|
||||
|
||||
```bash
|
||||
docker rm -f iotlcm-docs
|
||||
docker run -d --name iotlcm-docs --restart unless-stopped -p 8019:80 iotlcm-docs:$NEW_SHA
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [使用手册](/manual/) —— Web 管理端与小程序端操作说明
|
||||
- [OpenAPI 接口文档](/openapi/) —— V3 接口鉴权与调用说明
|
||||
| 场景 | Node | Docker | 访问路径 | 关键动作 | 详细 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 本地改文档 | 必需 | 不需要 | `/docs/` | `npm run dev` | [本地开发](./local-dev) |
|
||||
| 生产（推荐） | 仅构建阶段 | 必需 | `/docs/` | `docker build` + nginx alias | [Docker 部署](./docker-nginx) |
|
||||
| 静态托管（子路径） | 仅构建阶段 | 不需要 | `/docs/` | 产物放 `docs/` 子目录 | [静态托管](./static-hosting) |
|
||||
| 静态托管（根路径） | 仅构建阶段 | 不需要 | `/` | 改 `base: '/'` 重新构建 | [静态托管](./static-hosting) |
|
||||
| 对象存储 / CDN | 仅构建阶段 | 不需要 | `/docs/` | 上传 + 配 404 与默认首页 | [静态托管](./static-hosting) |
|
||||
| 内网离线 | 可在别处构建 | 可选 | `/docs/` | 只拷产物或改 FROM | [内网与离线](./offline) |
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: 本地开发与预览
|
||||
description: 改文档时用 dev 模式，热更新实时看效果
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 本地开发与预览
|
||||
|
||||
适用：修改文档内容、调整配置、本地看效果。
|
||||
|
||||
## 启动开发服务器
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
访问 **`http://127.0.0.1:5173/docs/`**
|
||||
|
||||
::: warning 地址必须带 /docs/
|
||||
`base: '/docs/'` 决定了 dev 服务器入口也在子路径下，直接访问 `http://127.0.0.1:5173/` 会 404。
|
||||
:::
|
||||
|
||||
改动 `docs/` 下任意 `.md` 文件会**热更新**，无需重启。按 `Ctrl+C` 退出。
|
||||
|
||||
## 局域网访问
|
||||
|
||||
需要让同网段其他机器访问时，把监听地址改为 `0.0.0.0`：
|
||||
|
||||
```bash
|
||||
npx vitepress dev . --host 0.0.0.0
|
||||
# 然后访问 http://<本机IP>:5173/docs/
|
||||
```
|
||||
|
||||
## 端口冲突
|
||||
|
||||
默认 5173，被占用时换端口：
|
||||
|
||||
```bash
|
||||
npx vitepress dev . --port 5174
|
||||
```
|
||||
|
||||
## 预览构建产物
|
||||
|
||||
`dev` 模式是源码实时编译，与最终产物有细微差异（如资源路径、代码分割）。发布前建议跑一次真实构建：
|
||||
|
||||
```bash
|
||||
npm run build # 产物在 .vitepress/dist
|
||||
npm run preview # http://127.0.0.1:4173/docs/
|
||||
```
|
||||
|
||||
`preview` 只是本地起静态服务验证产物，**不要用于生产**。
|
||||
|
||||
## 目录结构
|
||||
|
||||
新增页面时按此结构放置：
|
||||
|
||||
```text
|
||||
iotlcm-docs/
|
||||
├── docs/ # 文档源（VitePress srcDir）
|
||||
│ ├── index.md # 站点首页
|
||||
│ ├── manual/ # 使用手册
|
||||
│ │ ├── web/ # Web 管理端
|
||||
│ │ └── mini-program/ # 小程序端
|
||||
│ ├── openapi/ # OpenAPI 合同
|
||||
│ ├── deploy/ # 部署手册（本手册）
|
||||
│ └── public/ # 静态资源，映射到站点根路径
|
||||
│ └── images/ # 文档配图
|
||||
└── .vitepress/
|
||||
├── config.mts # 站点配置（导航、侧边栏）
|
||||
└── theme/ # 主题定制
|
||||
```
|
||||
|
||||
## 新增页面的步骤
|
||||
|
||||
1. 在 `docs/` 下对应目录新建 `xxx.md`，写 frontmatter：
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 页面标题
|
||||
description: 页面描述
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 页面标题
|
||||
```
|
||||
|
||||
2. 在 `.vitepress/config.mts` 的 `sidebar` 中注册，否则左侧目录不会显示：
|
||||
|
||||
```ts
|
||||
sidebar: {
|
||||
'/deploy/': [
|
||||
{
|
||||
text: '部署手册',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: '概览', link: '/deploy/' },
|
||||
{ text: '新页面', link: '/deploy/xxx' },
|
||||
]
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
3. 图片放 `docs/public/images/`，正文用绝对路径引用（public 目录映射到站点根）：
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
## 构建产物结构
|
||||
|
||||
```text
|
||||
.vitepress/dist/
|
||||
├── index.html # 首页
|
||||
├── 404.html # 404 页
|
||||
├── favicon.png
|
||||
├── assets/ # JS / CSS / 字体（带 hash）
|
||||
├── images/ # 来自 docs/public/images
|
||||
├── manual/ # 各章节
|
||||
├── openapi/
|
||||
└── deploy/
|
||||
```
|
||||
|
||||
注意产物是**平铺**的，没有 `docs/` 子目录——这正是部署时需要处理路径前缀的原因，见 [路径前缀必读](./path-prefix)。
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: 内网与离线部署
|
||||
description: 无法访问公网 npm 时的构建与部署方案
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 内网与离线部署
|
||||
|
||||
适用：目标机器无法访问公网 npm 源或 Docker Hub。
|
||||
|
||||
## 方案 A：使用内网镜像源
|
||||
|
||||
机器能访问内网 npm 仓库时，直接指定 registry：
|
||||
|
||||
```bash
|
||||
npm ci --registry=https://your-internal-registry/
|
||||
```
|
||||
|
||||
长期使用可写入 `~/.npmrc`：
|
||||
|
||||
```bash
|
||||
npm config set registry https://your-internal-registry/
|
||||
```
|
||||
|
||||
## 方案 B：有网机器构建，只拷产物（最简单）
|
||||
|
||||
产物是纯静态文件，**目标机器不需要装 Node**：
|
||||
|
||||
```bash
|
||||
# 有网机器
|
||||
npm ci && npm run build
|
||||
tar czf iotlcm-docs-dist.tar.gz -C .vitepress/dist .
|
||||
|
||||
# 目标机器
|
||||
tar xzf iotlcm-docs-dist.tar.gz -C /var/www/iotlcm/www/docs
|
||||
```
|
||||
|
||||
注意 `docs` 子目录与 `base: '/docs/'` 的对应关系，详见 [静态托管部署](./static-hosting)。
|
||||
|
||||
## 方案 C：内网构建镜像
|
||||
|
||||
`Dockerfile` 里基础镜像来自 Docker Hub（`node:22-alpine`、`nginx:1.27-alpine`），内网环境需先同步到内部镜像仓库，然后修改 `Dockerfile` 的 `FROM`：
|
||||
|
||||
```dockerfile
|
||||
FROM your-registry/library/node:22-alpine AS builder
|
||||
# ... 中间不变
|
||||
FROM your-registry/library/nginx:1.27-alpine
|
||||
```
|
||||
|
||||
同步镜像：
|
||||
|
||||
```bash
|
||||
# 在有外网的机器上
|
||||
docker pull node:22-alpine
|
||||
docker tag node:22-alpine your-registry/library/node:22-alpine
|
||||
docker push your-registry/library/node:22-alpine
|
||||
|
||||
docker pull nginx:1.27-alpine
|
||||
docker tag nginx:1.27-alpine your-registry/library/nginx:1.27-alpine
|
||||
docker push your-registry/library/nginx:1.27-alpine
|
||||
```
|
||||
|
||||
::: tip 已内置国内 apk 源
|
||||
`Dockerfile` 的 builder 阶段已把 Alpine 源换成 `mirrors.aliyun.com`，无需额外处理。
|
||||
:::
|
||||
|
||||
## 方案 D：离线安装依赖
|
||||
|
||||
既不能访问公网 npm、也没有内网 registry 时，可在有网机器打包 `node_modules`：
|
||||
|
||||
```bash
|
||||
# 有网机器（与目标机器同架构、同 Node 大版本）
|
||||
npm ci
|
||||
tar czf iotlcm-docs-full.tar.gz \
|
||||
--exclude=.git --exclude=.vitepress/cache --exclude=.vitepress/dist .
|
||||
|
||||
# 目标机器
|
||||
tar xzf iotlcm-docs-full.tar.gz -C /opt/iotlcm-docs
|
||||
cd /opt/iotlcm-docs
|
||||
npm run build
|
||||
```
|
||||
|
||||
::: warning 架构与版本必须一致
|
||||
`node_modules` 里可能含平台相关的二进制依赖，跨架构（如 x86 → ARM）或跨 Node 大版本会失败。跨架构场景请用方案 B 直接拷产物。
|
||||
:::
|
||||
|
||||
## 方案对比
|
||||
|
||||
| 方案 | 需要外网 | 目标机器需 Node | 适用场景 |
|
||||
| --- | --- | --- | --- |
|
||||
| A 内网 registry | 否（有内网源） | 是 | 有内网 npm 仓库 |
|
||||
| B 只拷产物 | 仅在构建机 | **否** | 最通用，推荐 |
|
||||
| C 内网镜像 | 仅在同步镜像时 | 否（用 Docker） | 容器化生产环境 |
|
||||
| D 打包 node_modules | 仅在构建机 | 是 | 需在目标机器改文档后构建 |
|
||||
|
||||
::: tip 推荐优先级
|
||||
优先选 **B（只拷产物）**——最简单，目标机器零依赖。需要容器化则选 **C**。
|
||||
:::
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
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` 重新构建。
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: 静态托管部署
|
||||
description: 不使用 Docker 时，用 nginx / 对象存储 / CDN 托管静态产物
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# 静态托管部署
|
||||
|
||||
适用：已有 nginx / Apache / Caddy，或使用对象存储 / CDN，不想引入 Docker。
|
||||
|
||||
核心流程只有两步：**构建产物** → **托管静态文件**。
|
||||
|
||||
## 编译产物
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run build
|
||||
# 产物在 .vitepress/dist
|
||||
```
|
||||
|
||||
本地验证构建结果（不要用于生产）：
|
||||
|
||||
```bash
|
||||
npm run preview
|
||||
# http://127.0.0.1:4173/docs/
|
||||
```
|
||||
|
||||
## nginx：子路径挂载（推荐）
|
||||
|
||||
把产物放到一个 `docs` 子目录，即可与 `base` 天然对齐，**无需 alias**：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /var/www/iotlcm/www
|
||||
sudo cp -r .vitepress/dist /var/www/iotlcm/www/docs
|
||||
```
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name _;
|
||||
root /var/www/iotlcm/www;
|
||||
|
||||
location /docs/ {
|
||||
try_files $uri $uri.html $uri/ $uri/index.html =404;
|
||||
}
|
||||
|
||||
location = /docs {
|
||||
return 301 /docs/;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
此处 `root` 指向父目录、产物在 `docs/` 子目录下，`/docs/assets/app.js` 会自然映射到 `/var/www/iotlcm/www/docs/assets/app.js`，不需要 `alias`。
|
||||
|
||||
## nginx：根路径独占域名
|
||||
|
||||
若文档站独占一个域名、需要挂在 `/`，必须**改 `base` 后重新构建**：
|
||||
|
||||
```bash
|
||||
sed -i "s#base: '/docs/'#base: '/'#" .vitepress/config.mts
|
||||
npm run build
|
||||
```
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name docs.example.com;
|
||||
root /var/www/iotlcm-docs;
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri.html $uri/ =404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: danger 不要只改服务器配置
|
||||
`base` 与访问前缀必须一致。改了 nginx 却不改 `base`（或反之），一定会白屏。详见 [路径前缀必读](./path-prefix)。
|
||||
:::
|
||||
|
||||
## Apache
|
||||
|
||||
需要启用 `mod_rewrite`，用 `.htaccess` 做 cleanUrls 映射：
|
||||
|
||||
```apache
|
||||
<IfModule mod_rewrite.c>
|
||||
RewriteEngine On
|
||||
RewriteBase /docs/
|
||||
|
||||
# 已存在的文件/目录直接返回
|
||||
RewriteCond %{REQUEST_FILENAME} -f [OR]
|
||||
RewriteCond %{REQUEST_FILENAME} -d
|
||||
RewriteRule ^ - [L]
|
||||
|
||||
# 无后缀路径映射到 .html 或 index.html
|
||||
RewriteCond %{REQUEST_FILENAME}.html -f
|
||||
RewriteRule ^(.+)$ $1.html [L]
|
||||
|
||||
RewriteCond %{REQUEST_FILENAME}/index.html -f
|
||||
RewriteRule ^(.+)$ $1/index.html [L]
|
||||
</IfModule>
|
||||
```
|
||||
|
||||
产物目录放置方式与 nginx 子路径方案一致：`/var/www/html/docs/`。
|
||||
|
||||
## Caddy
|
||||
|
||||
Caddy 配置更简洁，`try_files` 语义与 nginx 类似：
|
||||
|
||||
```caddyfile
|
||||
example.com {
|
||||
handle_path /docs/* {
|
||||
root * /var/www/iotlcm-docs
|
||||
try_files {path} {path}.html {path}/index.html
|
||||
file_server
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
或产物放在子目录、不做前缀处理：
|
||||
|
||||
```caddyfile
|
||||
example.com {
|
||||
root * /var/www/iotlcm/www
|
||||
try_files {path} {path}.html {path}/index.html
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
## 对象存储 / CDN
|
||||
|
||||
产物是纯静态文件，可直接上传到 S3 / OSS / MinIO 等：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
# 上传 .vitepress/dist 全部内容到桶内 docs/ 前缀下
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- 上传时保持 `/docs/` 前缀（或改 `base` 后重新构建）
|
||||
- 配置**默认首页**为 `docs/index.html`
|
||||
- 配置 **404 页面**为 `docs/404.html`（产物已自带）
|
||||
- `cleanUrls: true` 意味着页面 URL 不带 `.html`，需对象存储支持「无后缀映射到 .html」，否则需关闭 `cleanUrls` 重新构建
|
||||
|
||||
::: tip 关闭 cleanUrls
|
||||
若对象存储不支持无后缀映射，编辑 `.vitepress/config.mts` 把 `cleanUrls: true` 改为 `false`，重新构建后页面 URL 会带 `.html` 后缀。
|
||||
:::
|
||||
|
||||
## pnpm / yarn
|
||||
|
||||
仓库同时提供 `package-lock.json` 与 `pnpm-lock.yaml`。使用 pnpm：
|
||||
|
||||
```bash
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
npm 与 pnpm 二选一即可，**不要混用**（会产生不一致的 `node_modules`）。
|
||||
Reference in New Issue
Block a user