部署您的 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

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

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

平台指南 ​

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

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

• 构建命令: npm run docs:build
• 输出目录: docs/.vitepress/dist
• Node 版本: 18 (or 以上)

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.遵循官方文档。

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。