Astro SSR完全ガイド：3ステップでサーバーサイドレンダリングを有効化

はじめに

Astroで構築したブログがLighthouseで95点以上を叩き出し、悦に入っているところに、「ユーザーログイン機能機能を追加したいんだけど」という要望が。
「えっ、静的サイトでログイン？」と慌ててドキュメントを読み漁るも、SSR、SSG、Hybrid、Adapter…と専門用語のオンパレードで頭が痛くなった経験はありませんか？

私も初めてAstroのSSRに触れたときはそうでした。「Astroは静的で高速」が売りなのに、サーバーサイドレンダリングを入れたら遅くなるのでは？ Vercel、Netlify、Node.js…どのアダプターを選べばいいの？

実は、AstroのSSR設定は思っているよりずっとシンプルです。この記事では、いつSSRを使うべきか、各アダプターの素早い設定方法、そしてSSRとSSGを共存させる「Hybridモード」について、最も分かりやすく解説します。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

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

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

最も単純な判断基準はこれです：「内容はビルド時に決まっているか、それともアクセスするたびに変わるか？」

SSG（Static Site Generation） は、レストランの作り置き弁当のようなものです。朝のうちにシェフが作っておき、注文が入ったらすぐ出す。爆速です。ブログ記事、製品紹介、会社概要など、内容が頻繁に変わらないものに最適です。

SSR（Server-Side Rendering） は、オーダーごとの調理です。注文が入ってからシェフが作ります。「おかえりなさい、〇〇さん」という表示や、リアルタイムの株価、カートの中身など、人や時間によって表示が変わるものはSSRが必須です。

具体的に、以下の5つのシナリオのいずれかに当てはまるなら、SSRを検討すべきです：

1. ユーザー認証とパーソナライズ
   ログイン機能が代表的です。誰がログインするかビルド時には分かりません。「学習の続き：第5課」のような個別の進捗表示もSSRが必要です。
2. リアルタイムデータ表示
   天気予報、株価、スポーツの試合経過など、分単位で変わるデータ。毎分ビルドするわけにはいきませんよね。
3. データベース検索
   ECサイトの商品検索など、検索クエリによって結果が変わる場合、すべての組み合わせページを事前に作っておくのは不可能です。
4. APIルート
   フォーム送信、ファイルアップロード、バックエンド処理。AstroのSSRモードならAPIルート（src/pages/api/xxx.js）を作れるので、別のバックエンドサーバーを立てる必要がなくなります。
5. A/Bテストと地域別表示
   アクセス元の国によって言語を変えたり、時間帯でコンテンツを変えたりする場合。

逆に、「ブログ記事の詳細ページ」はSSRにする必要はありません。内容は固定なので、SSGで生成してCDNから配信する方が高速でサーバーコストも安く済みます。

Hybridモード：いいとこ取り

Astro 2.0で導入されたHybridモードは画期的です。静的ページはSSGで、動的ページだけSSRにする。例えばECサイトなら：

• トップページ、About、ヘルプ → SSG（高速）
• ログイン、マイページ、カート → SSR（動的）
• 商品詳細 → SSG（ほぼ固定）
• 検索結果 → SSR（動的）

これが最強の構成です。

第2章：クイックスタート - 3ステップでSSR有効化

Node.jsアダプターでの設定例

まずは最も汎用的なNode.jsアダプターで設定してみましょう。自前のVPSやDocker環境へのデプロイに適しています。

ステップ1：アダプターの自動インストール

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

今すぐ始める →広告

プロジェクトのルートで以下のコマンドを実行します：

npx astro add node

このコマンドが勝手にやってくれること：

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

ステップ2：設定ファイルの確認

astro.config.mjs を開くと、以下のようになっているはずです：

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

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

output 設定について：

• 'static'（デフォルト）：全ページSSG
• 'server'：全ページSSR
• 'hybrid'：デフォルトSSG、指定ページのみSSR（おすすめ！）

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

npm run build

ビルド後、dist/server/entry.mjs というファイルが生成されます。これがサーバーのエントリーポイントです。

node ./dist/server/entry.mjs

これで http://localhost:4321 でSSRサーバーが立ち上がります。

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

ホスティングサービスを使う場合は、専用のアダプターを使うともっと簡単です。

Vercelアダプター

Vercelは個人開発の最強の味方です。

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

15%割引を入手 →広告

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（Incremental Static Regeneration）
Vercelアダプターならではの機能として、キャッシュ設定が可能です。

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

これにより、SSRでありながらSSGのような高速レスポンスを実現できます。

Netlifyアダプター

Netlifyも人気です。特にEdge Functions（エッジでの処理）に強いです。

npx astro add netlify

Cloudflareアダプター

グローバルなCDNエッジで動くCloudflare Workersを使う場合です。

npx astro add cloudflare

注意点として、Cloudflare WorkersはNode.jsの全APIが使えるわけではありません（ファイルシステム操作など）。

第4章：Hybridモードの実践

一つのプロジェクトでSSRとSSGを共存させる

これがAstroの真骨頂です。
設定を 'hybrid' にします：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // デフォルトはSSG
  adapter: node(),
});

この設定だと、基本はすべてSSGになります。
SSRにしたいページ（例：src/pages/dashboard.astro）の先頭に、以下の一行を追加します：

---
export const prerender = false; // SSG（プリレンダリング）をオフにする＝SSR
// ここで動的な処理を書く
const user = Astro.cookies.get('user');
---

たったこれだけです！
逆に output: 'server' （基本SSR）の設定にしておいて、静的なページだけ export const prerender = true; と書くこともできます。

私は迷ったら output: 'hybrid' を推奨 します。基本を静的にしておけばパフォーマンスが保証され、必要な部分だけ動的にできるからです。

第5章：よくあるトラブルと解決策

Q: Astro.clientAddress が使えない
A: output: 'static' のままになっていませんか？ SSRモード（server か hybrid）に変更してください。

Q: デプロイしたら404になる
A: ビルドコマンドや出力ディレクトリの設定ミスが多いです。

• Vercel: 出力設定は自動で任せるのが吉。
• Netlify: publishディレクトリは dist (static) または .netlify (SSR) です。

Q: 環境変数が読み込めない
A: クライアント側（ブラウザ）で使う環境変数は PUBLIC_ というプレフィックスが必要です。サーバー側だけで使う秘密鍵などはプレフィックスなしでOKです。

まとめ

1. SSRは万能薬ではない：静的でいいならSSGが最強・最速。
2. Hybridモードを活用せよ：SSGの速さとSSRの柔軟性を両立できるAstroのキラー機能。
3. アダプター設定は自動：npx astro add xxx コマンドで一発。

SSRを恐れる必要はありません。必要な場所にだけ適用し、快適なAstroライフを！

3 min read · 公開日: 2025年12月2日 · 更新日: 2026年1月22日

Easton

技術開発