部署

以下指南基于一些共同的假设：

VitePress 站点位于项目的 docs 目录中。
你正在使用默认的构建输出目录 (.vitepress/dist)。

VitePress 作为本地依赖项安装在项目中，并且你已在 package.json 中设置以下脚本：

json

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

本地构建和测试

运行此命令来构建文档：
sh
```
$ npm run docs:build
```
1
构建完成后，通过运行以下命令在本地预览它：
sh
```
$ npm run docs:preview
```
1
preview 命令将启动一个本地静态 Web 服务器，该服务器在 http://localhost:4173 上提供 .vitepress/dist 中的文件。这是检查生产构建在本地环境中是否正常的简便方法。
你可以通过传递 --port 作为参数来配置服务器的端口。
json
```
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}
```
1
2
3
4
5
现在 docs:preview 方法将在 http://localhost:8080 启动服务器。

设置公共基础路径

默认情况下，我们假设站点将部署在域的根路径 (/) 上。如果站点将在子路径中提供服务，例如 https://mywebsite.com/zh/blog/，则需要在 VitePress 配置中将 base 选项设置为 '/zh/blog/'。

示例： 如果你使用 Github（或 GitLab）页面并部署到 user.github.io/repo/，请将 base 设置为 /repo/。

HTTP 缓存标头

如果你可以控制生产服务器上的 HTTP 标头，则可以配置 cache-control 标头以在重复访问时获得更好的性能。

生产构建对静态资源（JavaScript、CSS 和其他非 public 目录中的导入资源）使用散列文件名。如果你使用浏览器开发工具的网络选项卡检查生产预览，你将看到 app.4f283b18.js 之类的文件。

此 4f283b18 哈希是从此文件的内容生成的。相同的散列 URL 保证提供相同的文件内容——如果内容更改，URL 也会更改。这意味着你可以安全地为这些文件使用最强的缓存标头。所有此类文件都将放在输出目录的 assets/ 中，因此你可以为它们配置以下标头：

Cache-Control: max-age=31536000,immutable

Netlify _headers 文件示例

/assets/*
  cache-control: max-age=31536000
  cache-control: immutable

注意：_headers 文件应放在 public 目录中——在我们的例子中是 docs/public/_headers——以便将其逐字复制到输出目录。

Netlify 自定义标头文档

Vercel vercel.json 配置示例

json

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

注意：vercel.json 文件应放在存储库的根目录中。

Vercel 关于标头配置的文档

平台指南

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

设置新项目并使用仪表板更改这些设置：

构建命令： npm run docs:build
输出目录： docs/.vitepress/dist
Node 版本： 18（或更高版本）

警告

不要为 HTML 代码启用 Auto Minify 等选项。它将从输出中删除对 Vue 有意义的注释。如果被删除，你可能会看到激活不匹配错误。

GitHub Pages

在项目的 .github/workflows 目录中创建一个名为 deploy.yml 的文件，其中包含这样的内容：

yaml

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
#
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消注释
      # with:
      # version: 9
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # 部署工作
  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-pages@v4

警告

请确保 VitePress 配置文件中的 base 选项配置正确。有关更多详细信息，请参阅设置公共基础路径。

在存储库设置中的"Pages"菜单项下，选择"GitHub Actions"作为"Source"。
将更改推送到 main 分支并等待 GitHub Action 完成。你应该看到站点部署到 https://<username>.github.io/[repository]/ 或 https://<custom-domain>/，这取决于你的设置。你的站点将在每次推送到 main 分支时自动部署。

GitLab Pages

如果你想部署到 https://<username>.gitlab.io/<repository>/，请将 VitePress 配置文件中的 outDir 设置为 ../public。如果你想部署到 https://<username>.gitlab.io/，请将 base 选项配置为 '/'。

在项目根目录中创建一个名为 .gitlab-ci.yml 的文件，内容如下。每当你更改内容时，这将构建和部署你的站点：

yaml

# .gitlab-ci.yml
image: node:18
pages:
  cache:
    paths:
      - node_modules/
  script:
    - npm install
    - npm run docs:build
  artifacts:
    paths:
      - public
  only:
    - main

Azure Static Web Apps

查看官方文档。

在项目根目录中创建一个名为 .github/workflows/azure-static-web-apps-<RANDOM_NAME>.yml 的文件，内容如下（确保将占位符替换为你的值）：

yaml

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/"
          api_location: ""
          output_location: "docs/.vitepress/dist"
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

Firebase

在项目根目录中创建 firebase.json 和 .firebaserc：

firebase.json:

json

{
  "hosting": {
    "public": "docs/.vitepress/dist",
    "ignore": []
  }
}

.firebaserc:

json

{
  "projects": {
    "default": "<YOUR_FIREBASE_ID>"
  }
}

运行 npm run docs:build 后，运行此命令进行部署：
sh
```
firebase deploy
```
1

Surge

运行 npm run docs:build 后，运行此命令进行部署：
sh
```
npx surge docs/.vitepress/dist
```
1

Heroku

按照 heroku-buildpack-static 中给出的文档和指南进行操作。
在项目根目录中创建一个名为 static.json 的文件，其中包含以下内容：
json
```
{
  "root": "docs/.vitepress/dist"
}
```
1
2
3

Edgio

请参阅使用 Edgio 创建和部署 VitePress 应用程序。

Kinsta 静态站点托管

你可以按照这些说明在 Kinsta 上部署你的 Vitepress 站点。

部署 ​

本地构建和测试 ​

设置公共基础路径 ​

HTTP 缓存标头 ​

平台指南 ​

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render ​

GitHub Pages ​

GitLab Pages ​

Azure Static Web Apps ​

Firebase ​

Surge ​

Heroku ​

Edgio ​

Kinsta 静态站点托管 ​

部署

本地构建和测试

设置公共基础路径

HTTP 缓存标头

平台指南

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

GitHub Pages

GitLab Pages

Azure Static Web Apps

Firebase

Surge

Heroku

Edgio

Kinsta 静态站点托管