Astro SSR 設定完全ガイド：3 ステップで SSR を有効化、技術選定の迷いから解放

Astro ブログが Lighthouse 95+ で快適に動いているのに、突然上司から「ユーザーログイン機能を追加しよう」と言われた——そんな経験はありませんか。静的サイトでログインをどう実装するのか、公式ドキュメントを開くと SSR、SSG、Hybrid、アダプターといった用語が次々と現れ、ますます混乱する。

私も Astro SSR に初めて触れたとき、同じ感覚でした。Astro の売りは「速さ」なのに、サーバーサイドレンダリングを足すと遅くなるのでは？ Vercel、Netlify、Node.js とアダプターが多く、どれを選べばいいのか。設定ファイルの output や prerender とは何か。

実は Astro SSR の設定は、思っているほど複雑ではありません。本記事では、いつ SSR が必須か（SSG のままでは足りないケース）、各種アダプターの素早い設定方法、1 プロジェクトで SSR と SSG を併用する Hybrid モードまで、わかりやすく解説します。読み終えれば、自分のプロジェクトに SSR が必要か判断でき、30 分以内に設定も完了できるはずです。

第 1 章：SSR の基礎概念と技術選定

いつ SSG ではなく SSR が必要か？

最もシンプルな判断基準はこれです：内容はビルド時に決まるのか、アクセスのたびに変わる可能性があるのか？

SSG（Static Site Generation） は、レストランの作り置き弁当のようなもの。朝にシェフが作っておき、客が来たらすぐ出せる——超高速。ブログ記事、製品紹介、About ページなど、ほぼ変わらないコンテンツには SSG が最適です。

SSR（Server-Side Rendering） は、注文してから調理するスタイル。ログイン後の「おかえりなさい、太郎さん」、リアルタイム株価、カート内の商品数——人や時間によって表示が異なる場合は SSR が必須です。

プロジェクトに SSR が必要か迷ったら、以下 5 シーンのいずれかに当てはまるか確認してください。

1. ユーザー認証とパーソナライズ

典型例はログイン。ビルド時に誰がログインするか、どのユーザー名を表示するかは分かりません。以前作った学習プラットフォームでは、トップに「学習を続ける：第 5 課」を出す必要があり、ログインユーザーの進捗に応じた SSR が不可欠でした。

2. リアルタイムデータ表示

天気予報、株価、スポーツのスコア。データは毎分変わります。毎分サイトをビルドするわけにはいきません。SSR なら、アクセスのたびに最新データを取得できます。

3. データベースクエリ

EC サイトの商品検索は、キーワードごとに結果が異なります。すべての検索結果ページを事前生成するのは不可能。SSR なら、検索時に DB をリアルタイム照会して結果を返せます。

4. API ルート

フォーム送信、ファイルアップロード、サードパーティ API 呼び出しにはバックエンドロジックが必要です。Astro の SSR モードでは API ルート（src/pages/api/xxx.js）を作成でき、別途バックエンドサーバーを立てなくて済みます。

5. A/B テストとパーソナライズ推薦

地理的位置、アクセス時間、履歴行動に応じて異なるコンテンツを表示します。EC トップのおすすめ商品は人ごとに異なり、このパーソナライズには SSR が必須です。

ここで「ブログ記事の詳細ページも SSR にできる？」と聞かれることがあります。できますが、必要ありません。記事内容は固定なので、SSG で静的 HTML を生成し CDN 配信する方が速く、サーバーコストも低い。SSR は万能ではなく、必要な場所だけ使いましょう。

Hybrid モード：両方のいいとこ取り

Astro 2.0 で導入された Hybrid モードは賢い設計です。1 プロジェクト内で、静的ページは SSG、動的ページは SSR にできます。EC サイトの例：

• トップ、About、ヘルプ → SSG（高速ロード）
• ログイン、ユーザーセンター、カート → SSR（動的コンテンツ）
• 商品詳細 → SSG（内容固定）
• 検索結果 → SSR（リアルタイムクエリ）

この構成なら、静的ページの速度を保ちつつ動的機能も実現できます。知人のブログも同じ方式——記事一覧・詳細は SSG、コメント欄は SSR——で Lighthouse 95+ を維持しています。

第 2 章：クイックスタート — 3 ステップで SSR モードを有効化

ゼロから Astro SSR を設定する（Node.js アダプター）

SSR が必要と判断したら、設定に入りましょう。まずは最も汎用的な Node.js アダプターで説明します。自前サーバーや VPS デプロイに向いています。

第 1 ステップ：アダプターをワンクリックインストール

Astro 公式の自動設定コマンドをプロジェクトルートで実行：

npx astro add node

この 1 コマンドで以下が自動実行されます：

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

1. @astrojs/node パッケージのインストール
2. astro.config.mjs の更新
3. package.json の依存関係更新

実行後、ターミナルに緑のチェックが並べば成功です。バージョン指定などで手動インストールする場合：

npm install @astrojs/node

その後、設定ファイルを手動編集（次のステップ）。

第 2 ステップ：設定ファイルを編集

プロジェクトルートの astro.config.mjs を開きます。自動設定済みなら、すでに以下の内容があるはず：

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

export default defineConfig({
  output: 'server', // SSR モード有効化
  adapter: node({
    mode: 'standalone' // 独立サーバーモード
  }),
});

2 つの設定項目を押さえましょう。

output 設定：

• 'static'（デフォルト）：全ページ SSG、純粋な静的 HTML を出力
• 'server'：全ページ SSR、リクエストのたびに動的生成
• 'hybrid'：デフォルト SSG、ページ単位で SSR を有効化（おすすめ！）

mode 設定：

• 'standalone'：Astro が独立した Node.js サーバーを起動、直接デプロイ向け
• 'middleware'：ミドルウェアを生成、Express や Koa などに統合可能

私は通常 standalone を使います。Astro 付属サーバーで十分なことが多いからです。既存の Express バックエンドに Astro を組み込むなら middleware を選びます。

第 3 ステップ：ビルドと実行

設定が終わったらビルド：

npm run build

ビルド後、dist/ 配下に server/ フォルダができ、entry.mjs が SSR サーバーのエントリーポイントです。

SSR サーバーを起動：

node ./dist/server/entry.mjs

デフォルトでは http://localhost:4321 で起動。全ページが SSR になります。

開発環境でのデバッグ

開発時は毎回ビルド不要。以下で十分：

npm run dev

開発サーバーが SSR を自動サポートし、コード変更がリアルタイム反映されます。

よくあるトラブル

1. ポートが使用中：4321 が使われている場合、環境変数で変更：

   PORT=3000 node ./dist/server/entry.mjs

2. adapter モジュールが見つからない：@astrojs/node がインストールされているか確認し、npm install で依存関係を再インストール

3. ページ 404：src/pages/ のファイル配置が正しいか確認。SSR モードでも Astro のルーティング規則は同じ

SSR 設定は本当にこれだけです。初回は開始から起動成功まで 5 分もかかりませんでした。Vercel や Netlify デプロイなら専用アダプターがあり、さらに簡単——次章で詳しく説明します。

第 3 章：主要アダプターの設定詳解

Vercel、Netlify、Cloudflare はどう選ぶ？

Vercel、Netlify、Cloudflare にホスティングするなら、SSR 設定はさらに簡単です。各プラットフォーム向けに Astro 公式がアダプターをメンテナンスしており、ほぼゼロ設定でデプロイできます。

Vercel アダプター — Serverless 関数の定番

Vercel は個人プロジェクトで最もよく使うプラットフォーム。無料枠も十分で、設定もシンプル：

npx astro add vercel

このコマンドですべて自動設定されます。設定ファイルは次のとおり：

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

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Vercel 独自機能：ISR（インクリメンタル静的再生成）

Vercel ならではの機能で、SSR ページを SSG のように高速化できます。初回アクセス時に SSR で生成し、一定時間キャッシュ、期限切れ後に再生成。

adapter: vercel({
  isr: {
    expiration: 60, // 60 秒間キャッシュ
  },
}),

ニュースサイトなら、記事詳細は 1 分に 1 回更新で十分。ISR なら SSR の柔軟性と SSG の速度を両立できます。

Vercel デプロイ手順：

1. アダプターを設定
2. コードを GitHub にプッシュ
3. Vercel コンソールでプロジェクトをインポート
4. ビルドコマンド：npm run build（自動認識）
5. デプロイをクリック——完了

Netlify アダプター — Edge Functions に強い

Netlify も人気のホスティング。静的サイト + 動的機能の組み合わせに向いています。

npx astro add netlify

設定ファイル：

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

export default defineConfig({
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true, // Edge ミドルウェアを有効化
  }),
});

edgeMiddleware とは？

ミドルウェアロジック（認証、リダイレクトなど）をエッジノードで実行し、レスポンスを高速化します。ユーザーの地理的位置に応じた言語切り替えなどに有用です。

Netlify のリダイレクト設定

Netlify はリダイレクトを自動処理できます。/old-page を /new-page にリダイレクトしたい場合、プロジェクトルートに _redirects ファイルを作成：

/old-page  /new-page  301

デプロイ後、コード変更なしで有効になります。

Cloudflare アダプター — グローバル CDN 加速

ユーザーが世界中にいるなら Cloudflare が最適。Workers は 300+ データセンターで動作し、レイテンシが極めて低い。

npx astro add cloudflare

設定ファイル：

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Cloudflare の制限

Cloudflare Workers の実行環境は Node.js と完全には同じではなく、一部 API（fs ファイルシステムなど）が使えません。これらに依存するプロジェクトでは Cloudflare は不向きかもしれません。

アダプター比較表

選択の目安：

• ブログ、ドキュメント：Vercel または Netlify。無料枠で十分、デプロイも簡単
• EC、SaaS：Vercel（ISR が便利）、または自前 Node.js（完全制御）
• 国際化プロダクト：Cloudflare（グローバル加速）
• エンタープライズ：自前 Node.js（データプライバシー、完全掌握）

絶対的な正解はありません。プロジェクトの要件と予算次第。私のブログは Vercel、クライアントの企業サイトは自前サーバー——どちらも問題なく運用しています。

第 4 章：Hybrid 混合レンダリング実践

1 プロジェクトで SSR と SSG を同時利用

純 SSR の設定を説明したので、ここが本題——Hybrid モード。Astro の真骨頂で、SSG の速度と SSR の柔軟性を同時に享受できます。

Hybrid モードの設定

output を 'hybrid' に変更するだけ：

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

export default defineConfig({
  output: 'hybrid', // デフォルト SSG、必要に応じ SSR
  adapter: node(),
});

この設定では、デフォルトで全ページが SSG。SSR が必要なページに 1 行追加するだけ。

ページ単位でレンダリング方式を制御

特定ページを SSR にするには、frontmatter に 1 行追加：

// src/pages/dashboard.astro（SSR）

---

export const prerender = false; // プリレンダリングをオフ = SSR
const user = Astro.cookies.get('user');

---

<h1>おかえりなさい、{user?.name}</h1>
<p>未読メッセージ {user?.notifications} 件</p>

これだけです！prerender = false は「ビルド時に生成せず、アクセス時に動的生成する」という意味。

逆に output: 'server'（全ページ SSR）で、特定ページだけ SSG にしたい場合：

// src/pages/about.astro（SSG）

---

export const prerender = true; // ビルド時に強制生成

---

<h1>About</h1>
<p>内容が変わらないページは事前生成で超高速。</p>

要点まとめ（混同しないために）：

最初はよく逆に設定していました。覚え方：hybrid は SSG 優先、server は SSR 優先。

実践例：ブログ + ユーザーシステム

記事表示とユーザーログインを持つブログプラットフォームの理想構成：

プロジェクト構造：

src/pages/
├── index.astro          // トップ（SSG）
├── about.astro          // About（SSG）
├── blog/
│   ├── [slug].astro     // 記事詳細（SSG）
│   └── index.astro      // 記事一覧（SSG）
├── login.astro          // ログイン（SSR）
├── dashboard.astro      // ユーザーセンター（SSR）
└── api/
    └── comments.js      // コメント API（SSR）

設定ファイル：

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // デフォルト SSG
  adapter: vercel(), // Vercel にデプロイ
});

静的ページ（特別な設定不要）：

// src/pages/blog/[slug].astro

---

// prerender 未設定 = デフォルト SSG
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;

---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

動的ページ（SSR が必要）：

// src/pages/dashboard.astro

---

export const prerender = false; // SSR 有効化

// ログイン状態を確認
const token = Astro.cookies.get('token')?.value;
if (!token) {
  return Astro.redirect('/login');
}

// DB からユーザー情報を取得
const user = await fetch(`https://api.example.com/user`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(res => res.json());

---

<div>
  <h1>ようこそ、{user.name}</h1>
  <p>メール：{user.email}</p>
  <p>最終ログイン：{user.lastLogin}</p>
</div>

API ルート（自動 SSR）：

// src/pages/api/comments.js
export async function POST({ request }) {
  const { articleId, content } = await request.json();

  // コメントを DB に保存
  await db.comments.insert({
    articleId,
    content,
    createdAt: new Date(),
  });

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
}

export async function GET({ url }) {
  const articleId = url.searchParams.get('articleId');

  // DB からコメントを取得
  const comments = await db.comments.findMany({
    where: { articleId },
    orderBy: { createdAt: 'desc' }
  });

  return new Response(JSON.stringify(comments), {
    headers: { 'Content-Type': 'application/json' }
  });
}

この構成のメリット：

1. 静的ページ（記事、トップ）は依然として超高速——Lighthouse 95+、すべて CDN 配信
2. 動的ページ（ユーザーセンター）はリアルタイムデータ——ユーザーごとに表示が異なる
3. API ルートでバックエンド能力——別途バックエンドサーバー不要
4. ビルド時間が短い——静的ページだけプリレンダリング、動的ページはビルド時間を消費しない

以前のプロジェクトでは、50 記事 + ユーザーシステムでビルド 20 秒、静的ページは瞬時に開き、動的ページも 100ms 以内。Hybrid モードは本当にベストプラクティスです。

第 5 章：よくある問題とベストプラクティス

SSR 設定の落とし穴と解決策

SSR 設定で何度もつまずいた経験から、よくある問題と解決策をまとめます。

問題 1：Astro.clientAddress is only available when using output: 'server' エラー

原因：コードで Astro.clientAddress（ユーザー IP 取得）を使っているのに、設定の output が 'static' のまま。

解決策：

// astro.config.mjs
export default defineConfig({
  output: 'server', // または 'hybrid'
  adapter: node(),
});

Astro.clientAddress、Astro.cookies、Astro.redirect() などの動的 API は SSR モードでのみ使えます。

問題 2：デプロイ後 404、ローカル開発は正常

原因：アダプター設定ミス、またはデプロイ先のビルドコマンド/出力ディレクトリ設定エラー。

解決策：

Vercel デプロイ：

• ビルドコマンド：npm run build
• 出力ディレクトリ：.vercel/output（自動）
• vercel.json でルートを手動設定せず、Astro に任せる

Netlify デプロイ：

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

• ビルドコマンド：npm run build
• 公開ディレクトリ：dist（静的）または .netlify（SSR）
• 404 が続く場合、netlify.toml を確認：

  [build]
    command = "npm run build"
    publish = "dist"

問題 3：SSR ページのロードが 2 秒超

原因：サーバー性能不足、または DB クエリが遅い。

解決策：

1. キャッシュを使う：

   // src/pages/api/news.js
   export async function GET() {
     const cached = await redis.get('news');
     if (cached) {
       return new Response(cached, {
         headers: {
           'Content-Type': 'application/json',
           'Cache-Control': 'public, max-age=60' // 60 秒キャッシュ
         }
       });
     }
   
     const news = await fetchNewsFromDB();
     await redis.set('news', JSON.stringify(news), 'EX', 60);
   
     return new Response(JSON.stringify(news), {
       headers: {
         'Content-Type': 'application/json',
         'Cache-Control': 'public, max-age=60'
       }
     });
   }

2. DB クエリを最適化：

   • インデックス追加
   • JOIN 削減
   • 必要なフィールドだけ取得

3. ISR を検討（Vercel 利用時）：

   adapter: vercel({
     isr: { expiration: 300 } // 5 分キャッシュ
   }),

問題 4：環境変数がクライアント側で取得できない

原因：Astro の環境変数にはサーバー側とクライアント側の区別がある。

解決策：

サーバー側（SSR ページ、API ルート）：

const secret = import.meta.env.SECRET_KEY; // すべての環境変数が使える

クライアント側（ブラウザの JavaScript）：

const apiUrl = import.meta.env.PUBLIC_API_URL; // PUBLIC_ プレフィックス必須

.env ファイル設定：

SECRET_KEY=abc123          # サーバー側のみ
PUBLIC_API_URL=https://api.example.com  # クライアント・サーバー両方

問題 5：adapter.setApp is not a function エラー

原因：Astro とアダプターのバージョン非互換。

解決策：

# 最新版に更新
npm update astro @astrojs/node

# または互換バージョンを指定（公式ドキュメント参照）
npm install astro@latest @astrojs/node@latest

Astro とアダプターを最新版に保てば、通常は問題ありません。

ベストプラクティスまとめ

1. デフォルトは Hybrid モード：全ページ SSR 必須でなければ output: 'hybrid' が最適
2. 必要なページだけ SSR：本当に動的レンダリングが必要なページだけ prerender = false
3. 静的アセットは CDN 経由：画像、CSS、JS は public/ に配置、自動 CDN 配信
4. キャッシュ戦略：ニュース一覧など変わりにくい動的コンテンツはキャッシュや ISR で負荷軽減
5. 環境変数を分離：機密情報はサーバー側、公開設定は PUBLIC_ プレフィックス
6. パフォーマンスを監視：Vercel Analytics や Google Analytics で SSR ページの応答時間を追跡

結論

要点は 3 つです。

1. SSR は万能ではなく、必要な場所だけ使う

SSR に興奮しすぎず、SSG が古いわけでもない。静的ページは SSG、動的ページは SSR——多くのプロジェクトでは Hybrid が最適。ブログ全体を SSR にした例も見ましたが、記事内容は変わらないので SSG + CDN の方が速く、結果としてパフォーマンスが下がりました。

2. アダプターはデプロイ先で選ぶ。設定は本当に簡単

Vercel/Netlify/Cloudflare なら npx astro add [platform] 一行。自前サーバーなら npx astro add node も 5 分程度。ドキュメントを恐れる必要はなく、実際の操作は見た目よりずっと簡単です。

3. Hybrid モードで両方のいいとこ取り

これが Astro の真骨頂。静的ページは Lighthouse 95+ を維持し、動的ページでパーソナライズを実現。ビルド時間も増えず、サーバーコストも爆発しません。今のプロジェクトでは、第一選択が Hybrid モードです。

次のアクション

本記事を読んだら：

1. すぐ試す：Astro プロジェクトで npx astro add node を実行、5 分で SSR を体験
2. 要件を整理：どのページが動的レンダリング必要か、どれが静的のままでよいかリストアップ
3. 深掘り：Astro の Server Islands（サーバーアイランド）機能——SSG ページ内に SSR コンポーネントを埋め込める、より柔軟な方式

設定で困ったら、Astro 公式 Discord コミュニティで質問するのがおすすめ。返信も早く、雰囲気も良好です。

最後に：過剰最適化は避けましょう。サイトのトラフィックが少ない（日 PV 1 万未満）なら静的サイトで十分。SSR で複雑さを増やす必要はありません。技術選定はビジネスに合わせ、使うためだけに使わない。

設定がうまくいくことを願っています。質問があればコメントでどうぞ！