部署您的 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 指令碼將啟動一個本機靜態網路伺服器，該伺服器將在 https://127.0.0.1:4173 提供輸出目錄 .vitepress/dist。您可以在推送到正式環境之前使用此方法來確保一切正常。
您可以傳遞 --port 作為引數來設定伺服器的埠號。
json
```
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}
```
現在 docs:preview 方法將在 https://127.0.0.1:8080 啟動伺服器。

設定公開基本路徑

預設情況下，我們假設網站將部署在網域的根路徑 (/) 中。如果您的網站將在子路徑中提供服務，例如 https://mywebsite.com/blog/，則您需要在 VitePress 設定檔中將 base 選項設定為 '/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

Example Netlify _headers file

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

Note: the _headers file should be placed in the public directory - in our case, docs/public/_headers - so that it is copied verbatim to the output directory.

Netlify custom headers documentation

Example Vercel config in vercel.json

json

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

Note: the vercel.json file should be placed at the root of your repository.

Vercel documentation on headers config

平台指南

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

設定一個新專案，並使用您的儀表板變更這些設定

建置指令： npm run docs:build
輸出目錄： docs/.vitepress/dist
Node 版本： 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 靜態網頁應用程式

遵循官方文件。
在設定檔中設定這些值（並移除您不需要的值，例如 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 靜態網站代管

您可以按照這些說明，在 Kinsta 上部署您的 Vitepress 網站。

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 靜態網頁應用程式 ​

Firebase ​

Surge ​

Heroku ​

Edgio ​

Kinsta 靜態網站代管 ​

Stormkit ​

Nginx ​

部署您的 VitePress 網站

在本地建置和測試

設定公開基本路徑

HTTP 快取標頭

平台指南

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

GitHub Pages

GitLab Pages

Azure 靜態網頁應用程式

Firebase

Surge

Heroku

Edgio

Kinsta 靜態網站代管

Stormkit

Nginx