Files

T

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

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

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

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

3.7 KiB

Raw Blame History

title, description, outline

title	description	outline
静态托管部署	不使用 Docker 时，用 nginx / 对象存储 / CDN 托管静态产物	deep

静态托管部署

适用：已有 nginx / Apache / Caddy，或使用对象存储 / CDN，不想引入 Docker。

核心流程只有两步：构建产物 → 托管静态文件。

编译产物

npm ci
npm run build
# 产物在 .vitepress/dist

本地验证构建结果（不要用于生产）：

npm run preview
# http://127.0.0.1:4173/docs/

nginx：子路径挂载（推荐）

把产物放到一个 docs 子目录，即可与 base 天然对齐，无需 alias：

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

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 后重新构建：

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

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（或反之），一定会白屏。详见路径前缀必读。 :::

Apache

需要启用 mod_rewrite，用 .htaccess 做 cleanUrls 映射：

<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 类似：

example.com {
    handle_path /docs/* {
        root * /var/www/iotlcm-docs
        try_files {path} {path}.html {path}/index.html
        file_server
    }
}

或产物放在子目录、不做前缀处理：

example.com {
    root * /var/www/iotlcm/www
    try_files {path} {path}.html {path}/index.html
    file_server
}

对象存储 / CDN

产物是纯静态文件，可直接上传到 S3 / OSS / MinIO 等：

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：

pnpm install --frozen-lockfile
pnpm run build

npm 与 pnpm 二选一即可，不要混用（会产生不一致的 node_modules）。

3.7 KiB Raw Blame History Unescape Escape