部署您的 VitePress 网站

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

VitePress 网站位于您项目中的 docs 目录中。
您使用的是默认的构建输出目录 (.vitepress/dist)。

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

json

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

本地构建和测试

运行此命令以构建文档
sh
```
$ npm run docs:build
```
构建完成后，通过运行以下命令在本地预览它
sh
```
$ npm run docs:preview
```
preview 命令将启动一个本地静态 Web 服务器，该服务器将在 http://localhost:4173 上提供输出目录 .vitepress/dist。您可以使用它来确保在推送到生产环境之前一切正常。
您可以通过传递 --port 作为参数来配置服务器的端口。
json
```
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}
```
现在，docs:preview 方法将在 http://localhost:8080 上启动服务器。

设置公共基本路径

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

示例：如果您使用的是 Github（或 GitLab）Pages 并部署到 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
节点版本：18（或更高版本）

警告

不要为 HTML 代码启用诸如自动缩小之类的选项。它将从输出中删除对 Vue 有意义的注释。如果它们被删除，您可能会看到水合不匹配错误。

GitHub Pages

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

yaml

# 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 you're
  # 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/checkout@v4
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # or pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - 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-artifact@v3
        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-pages@v4

警告

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

在您的存储库设置中，在“Pages”菜单项下，在“构建和部署 > 源”中选择“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-ci.yml 的文件，其中包含以下内容。这将在您对内容进行更改时构建和部署您的网站

yaml

image: node:18
pages:
  cache:
    paths:
      - node_modules/
  script:
    # - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled
    - npm install
    - npm run docs:build
  artifacts:
    paths:
      - public
  only:
    - main

Azure 静态 Web 应用

遵循官方文档。
在您的配置文件中设置这些值（并删除您不需要的值，例如 api_location）
- app_location: /
- output_location: docs/.vitepress/dist
- app_build_command: npm run docs:build

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
```

Surge

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

Heroku

请遵循 heroku-buildpack-static 中提供的文档和指南。
在项目的根目录创建一个名为 static.json 的文件，内容如下
json
```
{
  "root": "docs/.vitepress/dist"
}
```

Edgio

请参考将 VitePress 应用创建并部署到 Edgio。

Kinsta 静态网站托管

您可以按照以下说明，将您的 Vitepress 网站部署到 Kinsta。

Stormkit

您可以按照以下说明，将您的 VitePress 项目部署到 Stormkit。

Nginx

以下是一个 Nginx 服务器块配置示例。此设置包括针对常见文本资产的 gzip 压缩、用于使用适当的缓存头提供 VitePress 网站静态文件的规则，以及处理 cleanUrls: true 的规则。

nginx

server {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss 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 指令。

不要默认使用 index.html

try_files 解析不能像其他 Vue 应用程序那样默认使用 index.html。这会导致页面状态无效。

更多信息可以在官方 nginx 文档、这些问题 #2837、#3235 以及 Mehdi Merah 的这篇博客文章中找到。

部署您的 VitePress 网站 ​

本地构建和测试 ​

设置公共基本路径 ​

HTTP 缓存头 ​

平台指南 ​

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

GitHub Pages ​

GitLab Pages ​

Azure 静态 Web 应用 ​

Firebase ​

Surge ​

Heroku ​

Edgio ​

Kinsta 静态网站托管 ​

Stormkit ​

Nginx ​

部署您的 VitePress 网站

本地构建和测试

设置公共基本路径

HTTP 缓存头

平台指南

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

GitHub Pages

GitLab Pages

Azure 静态 Web 应用

Firebase

Surge

Heroku

Edgio

Kinsta 静态网站托管

Stormkit

Nginx