astro-build-deploy

Astro ビルドとデプロイ

Astroプロジェクトのビルドと各種プラットフォームへのデプロイ方法について説明します。

ビルドコマンド

# 本番ビルド
npm run build

# ビルド結果のプレビュー
npm run preview

ビルド結果はdist/ディレクトリに出力されます。

出力モード

Astroは3つの出力モードをサポートしています。

1. static（デフォルト）

すべてのページを事前にHTMLとして生成します。

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',  // デフォルト
});

特徴:

  • ビルド時にすべてのページが生成される
  • サーバー不要で静的ホスティングに配置可能
  • 最も高速なパフォーマンス

2. server（SSR）

すべてのページをリクエスト時にサーバーでレンダリングします。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

特徴:

  • リクエストごとにサーバーでHTMLを生成
  • 動的なコンテンツに対応
  • アダプターが必要

詳細はSSRとアダプターを参照してください。

3. hybrid

静的ページとサーバーレンダリングページを混在させます。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid',
  adapter: node({ mode: 'standalone' }),
});

ページごとにprerenderを指定：

---
// このページは静的に生成
export const prerender = true;
---

静的サイトのデプロイ

静的ビルド（output: 'static'）の場合、dist/ディレクトリを静的ホスティングサービスに配置するだけです。

主要なホスティングサービス

サービス特徴
NetlifyGit連携、自動ビルド、無料枠あり
VercelGit連携、自動ビルド、エッジ機能
Cloudflare Pages高速なCDN、無料枠あり
GitHub PagesGitHubリポジトリから直接ホスティング
AWS S3 + CloudFrontスケーラブル、カスタマイズ性高い

Netlifyへのデプロイ

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

Vercelへのデプロイ

Vercelは自動検出しますが、明示的に設定する場合：

// vercel.json
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

GitHub Pagesへのデプロイ

GitHub Actionsを使用した例：

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

GitHub Pagesでサブディレクトリにデプロイする場合、baseを設定：

// astro.config.mjs
export default defineConfig({
  site: 'https://username.github.io',
  base: '/repository-name',
});

サイト設定

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // サイトのURL（サイトマップ生成、canonical URLに使用）
  site: 'https://example.com',
  
  // ベースパス（サブディレクトリにデプロイする場合）
  base: '/blog',
  
  // トレイリングスラッシュの扱い
  trailingSlash: 'always',  // 'never' | 'always' | 'ignore'
});

ビルド最適化

// astro.config.mjs
export default defineConfig({
  build: {
    // インライン化するスタイルの最大サイズ
    inlineStylesheets: 'auto',
  },
  
  // 画像最適化（Astro 3.0+）
  image: {
    service: {
      entrypoint: 'astro/assets/services/sharp',
    },
  },
});

トラブルシューティング

404エラーが発生する

  • src/pages/配下のパスとファイル拡張子を確認
  • 動的ルートのgetStaticPaths()が正しく定義されているか確認
  • トレイリングスラッシュの設定を確認

ビルドが失敗する

  • Node.jsバージョンを確認（v18.20.8以降、v20.3.0以降、v22.0.0以降）
  • npm ciで依存関係をクリーンインストール
  • astro.config.mjsの構文エラーを確認

静的アセットが見つからない

  • public/ディレクトリに配置されているか確認
  • パスが正しいか確認（public/images/logo.png → /images/logo.png）
  • baseを設定している場合、パスにベースを含める

参考