VitePress サイトをデプロイする

以下のガイドは、次の前提に基づいています。

VitePress のサイトはプロジェクトの docs ディレクトリ内にある。
デフォルトのビルド出力ディレクトリ（.vitepress/dist）を使用している。
VitePress はプロジェクトのローカル依存としてインストールされており、package.json に次のスクリプトが設定されている。

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 サーバーを起動し、出力ディレクトリ .vitepress/dist を http://localhost:4173 で配信します。プロダクションへプッシュする前に見た目を確認できます。
--port 引数でサーバーのポートを設定できます。
json
```
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}
```
これで docs:preview は http://localhost: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

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

新しいプロジェクトを作成し、ダッシュボードで次の設定に変更します。

Build Command: npm run docs:build
Output Directory: docs/.vitepress/dist
Node Version: 20（以上）

WARNING

HTML の Auto Minify のようなオプションを有効にしないでください。Vue にとって意味のあるコメントが出力から削除され、削除されるとハイドレーションの不整合エラーが発生する可能性があります。

GitHub Pages

プロジェクトの .github/workflows ディレクトリに deploy.yml を作成し、以下の内容を記述します。

.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@v5
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      # - uses: pnpm/action-setup@v4 # Uncomment this block if you're using pnpm
      #   with:
      #     version: 9 # Not needed if you've set "packageManager" in package.json
      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 24
          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

WARNING

VitePress の base オプションが正しく設定されていることを確認してください。詳細は公開ベースパスの設定を参照してください。

リポジトリ設定の「Pages」メニューで、「Build and deployment > Source」を「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 の「Use unique domain」を有効にしている場合は base は不要です。

プロジェクトのルートに .gitlab-ci.yml を作成して、以下を追加します。これにより、コンテンツを更新するたびにサイトがビルド・デプロイされます。

.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

CloudRay

CloudRay でのデプロイ方法はこちらの手順を参照してください。

Firebase

プロジェクトのルートに firebase.json と .firebaserc を作成します。

firebase.json:

firebase.json

json

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

.firebaserc:

.firebaserc

json

{
  "projects": {
    "default": "<YOUR_FIREBASE_ID>"
  }
}

npm run docs:build の後、次のコマンドでデプロイします。
sh
```
 firebase deploy
```

Heroku

heroku-buildpack-static のドキュメントとガイドに従います。
プロジェクトのルートに static.json を作成し、以下を記述します。
static.json
json
```
{
  "root": "docs/.vitepress/dist"
}
```

Hostinger

Hostinger を使用して VitePress プロジェクトをデプロイするには、こちらの手順に従ってください。ビルド設定の構成では、フレームワークに VitePress を選択し、ルートディレクトリを ./docs に調整してください。

Kinsta

VitePress をこちらの手順に従ってデプロイできます。

Stormkit

VitePress プロジェクトを Stormkit にデプロイする手順を参照してください。

Surge

npm run docs:build の後、次のコマンドでデプロイします。
sh
```
 npx surge docs/.vitepress/dist
```

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 ドキュメント、Issue #2837、#3235、および Mehdi Merah 氏のブログ記事を参照してください。

VitePress サイトをデプロイする ​

ローカルでビルドしてテストする ​

公開ベースパスの設定 ​

HTTP キャッシュヘッダー ​

プラットフォーム別ガイド ​

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

GitHub Pages ​

GitLab Pages ​

Azure ​

CloudRay ​

Firebase ​

Heroku ​

Hostinger ​

Kinsta ​

Stormkit ​

Surge ​

Nginx ​

VitePress サイトをデプロイする

ローカルでビルドしてテストする

公開ベースパスの設定

HTTP キャッシュヘッダー

プラットフォーム別ガイド

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

GitHub Pages

GitLab Pages

Azure

CloudRay

Firebase

Heroku

Hostinger

Kinsta

Stormkit

Surge

Nginx