跳至内容

部署您的 VitePress 网站

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

  • VitePress 网站位于您项目中的 docs 目录中。

  • 您使用的是默认的构建输出目录 (.vitepress/dist)。

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

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

本地构建和测试

  1. 运行此命令以构建文档

    sh
    $ npm run docs:build
  2. 构建完成后,通过运行以下命令在本地预览它

    sh
    $ npm run docs:preview

    preview 命令将启动一个本地静态 Web 服务器,该服务器将在 https://127.0.0.1:4173 上提供输出目录 .vitepress/dist。您可以使用它来确保在推送到生产环境之前一切正常。

  3. 您可以通过传递 --port 作为参数来配置服务器的端口。

    json
    {
      "scripts": {
        "docs:preview": "vitepress preview docs --port 8080"
      }
    }

    现在,docs:preview 方法将在 https://127.0.0.1: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

  1. 在您项目的 .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 选项配置正确。有关更多详细信息,请参阅 设置公共基本路径

  2. 在您的存储库设置中,在“Pages”菜单项下,在“构建和部署 > 源”中选择“GitHub Actions”。

  3. 将您的更改推送到 main 分支,并等待 GitHub Actions 工作流完成。您应该看到您的网站部署到 https://<username>.github.io/[repository]/https://<custom-domain>/,具体取决于您的设置。您的网站将在每次推送到 main 分支时自动部署。

GitLab Pages

  1. 在 VitePress 配置中将 outDir 设置为 ../public。如果您想部署到 https://<username>.gitlab.io/<repository>/,请将 base 选项配置为 '/<repository>/'

  2. 在您项目的根目录中创建一个名为 .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 应用

  1. 遵循 官方文档

  2. 在您的配置文件中设置这些值(并删除您不需要的值,例如 api_location

    • app_location: /
    • output_location: docs/.vitepress/dist
    • app_build_command: npm run docs:build

Firebase

  1. 在项目的根目录创建 firebase.json.firebaserc 文件

    firebase.json:

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

    .firebaserc:

    json
    {
      "projects": {
        "default": "<YOUR_FIREBASE_ID>"
      }
    }
  2. 运行 npm run docs:build 后,运行以下命令进行部署

    sh
    firebase deploy

Surge

  1. 运行 npm run docs:build 后,运行以下命令进行部署

    sh
    npx surge docs/.vitepress/dist

Heroku

  1. 请遵循 heroku-buildpack-static 中提供的文档和指南。

  2. 在项目的根目录创建一个名为 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 的这篇 博客文章 中找到。