VitePress 部署完全指南从本地构建、Base 路径到各平台生产发布【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepressVitePress 是 Vite 与 Vue 驱动的静态站点生成器构建产物是纯静态文件因此可以被部署到几乎所有主流托管平台。本篇以仓库内 docs/ja/guide/deploy.md 为骨架系统讲解 VitePress 站点的完整发布链路先在本地构建与预览验证、再正确配置公开 Base 路径与 HTTP 缓存头最后覆盖 Netlify、Vercel、GitHub Pages、GitLab Pages、Firebase、Nginx 等十余种平台的部署方案。读完本文你将掌握从docs:build到生产环境上线的每一步并能针对子路径部署、静态资源长缓存、无扩展名 URLclean URLs等常见场景做出正确配置。部署前置条件下面的所有部署方案都基于以下三个前提请在开始前确认你的项目满足它们VitePress 站点位于项目的docs目录内使用默认的构建输出目录.vitepress/distVitePress 作为项目的本地依赖安装并在package.json中配置了以下脚本{ scripts: { docs:build: vitepress build docs, docs:preview: vitepress preview docs } }其中vitepress build docs负责构建vitepress preview docs负责本地预览。从 src/node/cli.ts 可以看到build与preview/serve是三个独立的 CLI 子命令build调用构建流程preview与serve都进入本地静态服务器逻辑serve是preview的别名。本地构建与测试上线之前务必在本地完整走一遍「构建 → 预览」流程确认产物与预期一致执行以下命令构建文档站点npm run docs:build构建完成后用以下命令进行本地预览npm run docs:previewpreview命令会启动一个本地静态 Web 服务器将输出目录.vitepress/dist的内容托管在http://localhost:4173下方便你在推送到生产环境前检查页面外观。4173这个默认端口并非随意设定它来自 src/node/serve/serve.ts 中的const port options.port ?? 4173。该预览服务器基于sirv实现对资源启用了etag、maxAge: 31536000与immutable缓存而对非资源文件如 HTML 页面强制使用no-cache见 serve.ts这与生产环境哈希资源长缓存、页面及时更新的缓存策略完全一致因此预览效果能很好地反映生产行为。如需修改端口使用--port参数{ scripts: { docs:preview: vitepress preview docs --port 8080 } }配置后docs:preview将在http://localhost:8080提供服务。公开 Base 路径的配置默认情况下VitePress 假定站点部署在域名根路径/下。如果你的站点要部署在子路径例如https://mywebsite.com/blog/就必须在 VitePress 配置中把base选项设置为/blog/。典型场景部署到 GitHub或 GitLabPages 的user.github.io/repo/时将base设置为/repo/。base选项有以下关键约束见 docs/en/reference/site-config.md类型为string默认值是/以子路径部署时必须以/开头并以/结尾例如/bar/唯一例外是./它会生成可迁移构建relocatable build页面内所有资源都引用相对自身位置的路径同一份产物可以在任何子路径下直接使用如 IPFS 网关、离线归档甚至可以直接从文件系统打开浏览无需重新构建base会被自动前置到其他配置中所有以/开头的 URL 上因此只需配置一次也可以在构建时用命令行临时覆盖vitepress build --base /base/。该参数在 src/node/build/build.ts 中处理会调用normalizeSiteBase规范化自动补全末尾斜杠。export default { base: /base/ }从源码看normalizeSiteBase见 src/node/config.ts负责规范化base传入时自动补末尾斜杠未传入时归一为/同时校验相对 base 只能是./。此外config.ts 中还做了一项防御性检查当base是相对路径./且开启了cleanUrls时构建会直接报错因为这种组合依赖服务端重写会破坏可迁移构建的 URL 语义。HTTP 缓存头配置如果你能控制生产服务器的 HTTP 头请务必为静态资源设置cache-control头以显著提升访客回访时的加载性能。在生产构建中静态资源JavaScript、CSS以及public目录之外的被导入资源都会使用带内容哈希的文件名。打开浏览器开发者工具的 Network 面板查看生产预览你会看到类似app.4f283b18.js的文件。这里的4f283b18哈希由文件内容生成相同哈希的 URL 必然返回相同内容内容一旦变化 URL 也随之变化。因此可以放心地对这些文件应用最强的缓存头——它们永远不会出现内容过期缓存未失效的问题。这些文件位于输出目录的assets/子目录下所以可以对assets路径设置如下响应头Cache-Control: max-age31536000,immutableassets/目录名来自构建配置的assetsDir选项其默认值正是assets见 docs/en/reference/site-config.md而资源文件名中的[hash]由打包阶段写入见 src/node/build/bundle.ts。这套内容哈希 永久缓存的设计正是前面提到预览服务器对资源使用immutable缓存的原因。::: details Netlify 的_headers文件示例/assets/* cache-control: max-age31536000 cache-control: immutable注意_headers文件需要放在 public 目录 中本例为docs/public/_headers构建时它会被原样复制到输出目录。:::::: details 通过vercel.json配置 Vercel 的示例{ headers: [ { source: /assets/(.*), headers: [ { key: Cache-Control, value: max-age31536000, immutable } ] } ] }注意vercel.json必须放置在仓库根目录。:::各平台部署指南Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render在平台控制台创建新项目后将以下配置填入部署设置Build Command构建命令npm run docs:buildOutput Directory输出目录docs/.vitepress/distNode VersionNode 版本20或更高::: warning 不要启用诸如 HTMLAuto Minify自动压缩之类的选项。它会删除输出中对 Vue 有意义的注释一旦被删除可能导致水合hydration不一致错误。 :::GitHub Pages在项目的.github/workflows目录下创建deploy.yml写入以下内容# Sample workflow for building and deploying a VitePress site to GitHub Pages # name: Deploy VitePress site to Pages on: # Runs on pushes targeting the main branch. Change this to master if youre # using the master branch as the default branch. push: branches: [main] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: contents: read pages: write id-token: write # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. concurrency: group: pages cancel-in-progress: false jobs: # Build job build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv5 with: fetch-depth: 0 # Not needed if lastUpdated is not enabled # - uses: pnpm/action-setupv4 # Uncomment this block if youre using pnpm # with: # version: 9 # Not needed if youve set packageManager in package.json # - uses: oven-sh/setup-bunv1 # Uncomment this if youre using Bun - name: Setup Node uses: actions/setup-nodev6 with: node-version: 24 cache: npm # or pnpm / yarn - name: Setup Pages uses: actions/configure-pagesv4 - name: Install dependencies run: npm ci # or pnpm install / yarn install / bun install - name: Build with VitePress run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: docs/.vitepress/dist # Deployment job deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} needs: build runs-on: ubuntu-latest name: Deploy steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4该工作流拆分为 build 与 deploy 两个 jobbuild 负责检出代码、安装依赖npm ci、执行docs:build并将docs/.vitepress/dist上传为 Pages artifactdeploy 在 build 成功后通过官方deploy-pagesaction 完成发布。工作流通过permissions授予pages: write与id-token: write并通过concurrency保证同一时间只有一个部署在运行。::: warning 务必确认 VitePress 的base选项已正确配置详见上文公开 Base 路径的配置。 :::在仓库设置的「Pages」菜单中将「Build and deployment Source」设置为「GitHub Actions」将改动推送到main分支并等待 GitHub Actions 执行完成。根据配置站点会被部署到https://username.github.io/[repository]/或https://custom-domain/。此后每次向main推送都会自动触发部署。GitLab Pages在 VitePress 配置中将outDir设置为../public。若部署到https://username.gitlab.io/repository/还需将base设置为/repository/若使用自定义域名、用户/组页面或开启了 GitLab 的「Use unique domain」则无需设置base。outDir的默认值是./.vitepress/dist相对项目根目录此处改到../public是为了让 GitLab Pages 直接从仓库的public目录发布产物。注意 VitePress 要求assetsDir必须位于outDir之内否则会报错见 src/node/config.ts。在项目根目录创建.gitlab-ci.yml写入以下内容。这样每次内容更新时站点都会自动构建并部署image: node:24 pages: cache: paths: - node_modules/ script: # - apk add git # Uncomment this if youre using small docker images like alpine and have lastUpdated enabled - npm install - npm run docs:build artifacts: paths: - public only: - main该流水线使用node:24镜像缓存node_modules加速安装构建产物public作为 artifacts 交给 GitLab Pages 发布且只在main分支触发。Azure按照 Azure Static Web Apps 官方文档的构建配置说明操作在配置文件如staticwebapp.config.json或构建配置中指定以下值删除api_location等不需要的项app_location/output_locationdocs/.vitepress/distapp_build_commandnpm run docs:buildCloudRayCloudRay 平台提供了专门的 VitePress 站点部署指引按其官方步骤在控制台完成项目接入与构建配置即可。Firebase在项目根目录创建firebase.json与.firebaserc{ hosting: { public: docs/.vitepress/dist, ignore: [] } }{ projects: { default: YOUR_FIREBASE_ID } }firebase.json的hosting.public指向构建产物目录ignore设为空数组避免意外忽略文件.firebaserc中的default需替换为你自己的 Firebase 项目 ID。执行npm run docs:build后运行以下命令部署firebase deployHeroku参考 Heroku 静态站点 buildpackheroku-buildpack-static的文档与使用指南在项目根目录创建static.json{ root: docs/.vitepress/dist }该配置告诉 buildpack 以docs/.vitepress/dist作为静态文件根目录。Hostinger在 Hostinger 的 Web 应用托管中部署 VitePress 项目时按其官方步骤操作即可。配置构建设置时框架选择 VitePress并将根目录Root Directory调整为./docs。KinstaKinsta 的静态站点托管支持 VitePress按其官方示例步骤完成项目导入与部署即可。StormkitStormkit 提供了专门的 VitePress 项目部署教程按其步骤在控制台完成构建与发布配置。Surge执行npm run docs:build后运行以下命令部署npx surge docs/.vitepress/distSurge 会提示你确认目标域名将docs/.vitepress/dist目录的内容发布到对应站点。Nginx下面是一份 Nginx 服务器块配置示例涵盖三类关键能力常见文本类资源的 gzip 压缩、VitePress 静态站点托管时的合理缓存头以及对cleanUrls: true的支持server { gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript; listen 80; server_name _; index index.html; location / { # content location root /app; # exact matches - reverse clean urls - folders - not found try_files $uri $uri.html $uri/ 404; # non existent pages error_page 404 /404.html; # a folder without index.html raises 403 in this setup error_page 403 /404.html; # adjust caching headers # files in the assets folder have hashes filenames location ~* ^/assets/ { expires 1y; add_header Cache-Control public, immutable; } } }该配置假设构建好的 VitePress 站点放在服务器上的/app目录如果文件位于其他位置请相应修改root指令。关键点解读try_files $uri $uri.html $uri/ 404实现了「精确文件 → 无扩展名回退 → 目录 → 404」的解析顺序这正是cleanUrls: true需要的服务端配合——访问/foo时无重定向地直接返回/foo.html。cleanUrls选项会让 VitePress 在构建时去掉 URL 中的.html后缀见 docs/en/reference/site-config.md但启用它要求托管服务器能在不重定向的情况下把/foo映射到/foo.htmlNginx 的try_files恰好满足这一要求内层location ~* ^/assets/对带哈希文件名的资源设置expires 1y与Cache-Control: public, immutable与上文「内容哈希 永久缓存」的策略一致error_page 404 /404.html与403 /404.html保证不存在的页面与无index.html的目录都能得到友好的 404 响应。::: warning 不要把 index.html 作为默认回退try_files的最后一项不要回退到index.html其他 Vue 应用常见的 SPA 做法。因为 VitePress 是预渲染的静态站点将其作为兜底会返回错误页面状态破坏 SEO 与用户体验。 :::部署检查清单最后把整个部署流程浓缩为一份自查清单本地验证先跑npm run docs:build与npm run docs:preview确认产物无误Base 路径子路径部署如 GitHub Pages 的/repo/时确认base以/开头和结尾自定义域名或根路径部署保持默认/资源缓存对assets/下的哈希文件设置max-age31536000, immutable平台配置按平台设置构建命令npm run docs:build与输出目录docs/.vitepress/distNode 版本不低于 20禁用 HTML 压缩不要在托管平台开启 Auto Minify 等会删除注释的选项避免水合错误cleanUrls若开启cleanUrls: true确认服务器支持无重定向的.html解析如上面的 Nginxtry_files方案且不要与相对 base./同时使用。以上配置与源码路径均可在当前仓库中直接查阅验证部署文档本体见 docs/ja/guide/deploy.mdbase、outDir、cleanUrls等选项的详细说明见 docs/ja/reference/site-config.mdCLI 命令解析见 src/node/cli.ts预览服务器与缓存策略见 src/node/serve/serve.ts构建参数处理见 src/node/build/build.ts。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
