跳到正文

发布文档站 ​

用一个包含首页和二级页面的 VitePress 站点练习静态部署。构建完成后,将 docs/.vitepress/dist 整个目录发布到静态服务器。

构建与本地预览 ​

在空目录中初始化 npm 项目并安装 VitePress。

bash
npm init -y
npm install -D vitepress

新建 docs/.vitepress/config.mjs,启用无扩展名链接。

js
import { defineConfig } from "vitepress";

export default defineConfig({ title: "My Docs", cleanUrls: true });

新建 docs/index.md。

md
# 我的文档

[快速开始](./guide/start)

新建 docs/guide/start.md。

md
# 快速开始

这个页面可以直接访问。

在项目根目录构建并启动预览。

bash
npx vitepress build docs
npx vitepress preview docs --host 127.0.0.1 --port 4173

打开 http://127.0.0.1:4173/,点击「快速开始」,再在新标签页直接打开 http://127.0.0.1:4173/guide/start 并刷新。两次都应显示「快速开始」。

Nginx ​

将下面的路由和缓存规则放进对应站点的 server 块,保留该站点的端口、TLS 和日志设置。

root 必须指向完整的构建产物;Nginx 的 http 块应已加载 mime.types,保证 JavaScript 和 CSS 使用正确 MIME 类型。

核心路由:

nginx
location / {
    try_files $uri $uri.html $uri/ =404;
    add_header Cache-Control "no-cache" always;
}

location ^~ /assets/ {
    try_files $uri =404;
    add_header Cache-Control "public, max-age=31536000, immutable";
}

location = /hashmap.json {
    try_files $uri =404;
    add_header Cache-Control "no-cache" always;
}

/guide/start 应读取 guide/start.html,/ 应读取 index.html。不存在的页面和资源返回 404。

不要写成 try_files $uri $uri/ /index.html,也不要把所有 404 改成根首页。 普通 Vue SPA 的首页兜底会让深层 URL 收到错误页面的 HTML;VitePress 的页面数据、预渲染内容与客户端路由因此不匹配。

配置修改后先运行 nginx -t;只有校验成功,再执行 nginx -s reload。这些操作由部署人员执行,源码构建不会修改服务器。

上传与缓存 ​

完整发布同一次构建中的 HTML、assets/、hashmap.json 及其他静态文件。HTML 和 hashmap.json 不采用长期不可变缓存;带哈希的资源可以长期缓存。使用 CDN 时同步检查其缓存和回源规则,不要在边缘把缺失 JS 改写为 HTML。

不要通过 CDN 的额外 HTML 压缩删除 Vue 的注释节点。替换线上产物后清理旧 HTML 和 hashmap.json 缓存,避免旧页面引用已经不存在的资源。

部署后验证 ​

在部署域名上直接访问并刷新 /guide/start,确认页面标题是「快速开始」。在浏览器的「网络」面板检查 JS 和 CSS 的响应类型,再访问一个不存在的页面及资源,例如 /missing-page 和 /assets/missing.js,两者都应返回 404。

其他静态托管 ​

发布目录同样是 docs/.vitepress/dist。启用 cleanUrls: true 时,托管服务需要将无扩展名 URL 映射到对应的 .html 文件。

独立域名使用默认根路径。部署到子目录时运行 npx vitepress build docs --base /docs/,同时调整静态服务的目录映射。