文档部署

本文说明如何将文档站和预览站部署到 Nginx。

一、构建

bash

pnpm build:all

产出目录（默认，可通过 .env.production 修改）：

文档：docs-dist/docs/
预览：docs-dist/mobile/

二、配置访问路径

在 .env.production 中设置与 Nginx 一致的路径，例如：

env

# 访问路径，需与 Nginx location 一致
DOCS_BASE=/docs/
DOCS_OUT_DIR=docs-dist/docs

PREVIEW_BASE=/mobile/
PREVIEW_OUT_DIR=docs-dist/mobile

# 文档右侧 iframe 的预览入口（生产环境填线上地址）
PREVIEW_ENTRY=https://你的域名/mobile/

三、放置产物

将构建产物拷贝到服务器，例如：

docs-dist/docs/ 内容 → 服务器目录 xxx/docs/
docs-dist/mobile/ 内容 → 服务器目录 xxx/mobile/

确保目录下直接包含 index.html、assets/ 等文件。

四、Nginx 配置示例

将 alias 路径和 location 路径按实际部署修改。

nginx

server {
    listen 1026;
    error_page 500 502 503 504 /50x.html;

    # 文档站
    location /docs {
        alias "D:/root/www/wwwroot/你的项目/docs/";
        index index.html;

        # 静态资源：找不到直接 404
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
            try_files $uri =404;
            expires 30d;
        }

        if ($request_filename ~* .*\.(?:htm|html)$) {
            add_header Cache-Control max-age=120;
        }
        try_files $uri $uri/ /docs/index.html;
    }

    # 预览站
    location /mobile {
        alias "D:/root/www/wwwroot/你的项目/mobile/";
        index index.html;

        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?|json)$ {
            try_files $uri =404;
            add_header Cache-Control "public, max-age=2592000";
        }

        if ($request_filename ~* .*\.(?:htm|html)$) {
            add_header Cache-Control "max-age=120";
        }
        try_files $uri $uri/ /mobile/index.html;
    }

    error_page 404 /404.html;
}

五、验证

文档：http://你的域名:1026/docs/
预览：http://你的域名:1026/mobile/
真机预览：手机访问 http://你的域名:1026/mobile/?component=TagDemo

六、常见问题

静态资源 404：检查 .env.production 的 DOCS_BASE、PREVIEW_BASE 是否与 Nginx location 路径一致。

刷新页面 404：确认 Nginx 有 try_files $uri $uri/ /docs/index.html（或 /mobile/index.html）兜底。

文档右侧预览打不开：检查 PREVIEW_ENTRY 是否为线上可访问地址。

文档部署 ​

一、构建 ​

二、配置访问路径 ​

三、放置产物 ​

四、Nginx 配置示例 ​

五、验证 ​