Skip to content
当前页导航

部署您的 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 服务器,该服务器将为http://localhost:4173的输出目录.vitepress/dist提供服务。您可以使用它来确保在投入生产之前一切看起来都很好。

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

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

现在,docs:preview方法将在http://localhost:8080启动服务器。

设置公共基本路径

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

示例: 如果您使用 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.json 中的 Vercel 配置示例
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 (or 以上)

WARNING

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

GitHub 页面

  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@v3
            with:
              fetch-depth: 0 # Not needed if lastUpdated is not enabled
          # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm
          - name: Setup Node
            uses: actions/setup-node@v3
            with:
              node-version: 18
              cache: npm # or pnpm / yarn
          - name: Setup Pages
            uses: actions/configure-pages@v3
          - name: Install dependencies
            run: npm ci # or pnpm install / yarn install
          - name: Build with VitePress
            run: npm run docs:build # or pnpm docs:build / yarn docs:build
          - name: Upload artifact
            uses: actions/upload-pages-artifact@v2
            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@v2

    WARNING

    请确保你的VitePress中base选项已经正确配置。详细信息请参考设置公共基础路径

  2. 在你的代码仓库设置中,找到"Pages"菜单项,在"Build and deployment > Source"下选择"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:16
    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.遵循官方文档

  1. 在配置文件中设置这些值(并删除不需要的值,例如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

本文档由全栈行动派(qzxdp.cn)翻译并整理