cdnとnuxtで実現する高速化の基礎と応用完全ガイド

2025 11/29

2025/11/29

はじめに

概要

本ドキュメントは、Nuxt.jsアプリケーションでCDN（Content Delivery Network）を効果的に利用する方法をまとめています。主にruntimeConfigでのcdnURL設定、環境変数を使った動的設定、静的サイト生成（SSG）との連携、WordPress連携時のキャッシュ最適化、Nuxt Contentの利用、ベースディレクトリの動的設定、OGPとCDN戦略について扱います。

目的

読み手が実務でCDNを導入・運用できることを目指します。例えば、画像や静的アセットをCDNに移してページ表示を早める、環境ごとにCDNのURLを切り替える、といった具体的な操作を想定しています。

対象読者

Nuxt.jsでサイトを構築する開発者や運用担当者、WordPressと連携するエンジニアを想定しています。基礎的なNuxtの知識があれば読み進められます。

本書の読み方

各章は独立して参照できます。まずは第2章でCDN設定の基礎を確認し、必要に応じて後続章で詳細な運用方法や最適化手法を参照してください。

Nuxt.jsでのCDN設定の基礎

概要

Nuxt.jsアプリでCDNを使うと、画像や静的ファイルを高速に配信できます。基本はnuxt.config.ts（またはnuxt.config.js）のruntimeConfig.public.cdnURLに絶対URLを設定することです。デフォルトは空文字（””）にしておくと、本番のみ有効にできます。

設定例

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      cdnURL: '' // ここにCDNの絶対URLを設定
    }
  }
})

環境ごとに変えたい場合は環境変数を使います（例: process.env.CDN_URL）。

コンポーネントでの利用

コンポーネントではuseRuntimeConfig()で参照します。

<script setup>
const config = useRuntimeConfig()
const logo = (config.public.cdnURL || '') + '/images/logo.png'
</script>
<template>
  <img :src="logo" alt="ロゴ" />
</template>

このようにすると、開発時はローカルパス、本番はCDN配信に切り替わります。

注意点

cdnURLは必ず絶対URL（例: https://cdn.example.com）にする
末尾のスラッシュ有無でパス結合が変わるので統一する
HTMLのheadやOGP画像でも同様に使えます

以上が基礎です。次章ではruntimeConfigの構造を詳しく見ていきます。

runtimeConfigの詳細な構造

構造の全体像

NuxtのruntimeConfigはサーバー側とクライアント側で使う設定を分けます。publicオブジェクトの中にappがあり、そこにbuildId、baseURL、buildAssetsDir、cdnURLなどが入ります。nitroにはenvPrefixなどのランタイム設定が入ります。

各プロパティの説明

buildId：ビルドごとに変わる識別子です。キャッシュ管理やアセットのバージョン判定に使います。例：”fe8767…”
baseURL：アプリのルートパスです。サブディレクトリで配信する場合に変更します。例：”/blog/”
buildAssetsDir：ビルド済みアセットのパスです。通常は”/_nuxt/”です。
cdnURL：静的アセットを配信するCDNのベースURLを指定します。例：”https://cdn.example.com”。設定するとアセットURLがCDN経由になります。
nitro.envPrefix：Nitroが参照する環境変数のプレフィックスです。例：”NUXT_”

cdnURLの使い方と注意点

cdnURLを設定すると画像やJS/CSSのURLがCDNベースになります。絶対URLで指定し、末尾のスラッシュの有無に注意してください。公開設定(public)はクライアントに見えるため、秘密情報は置かないでください。キャッシュ更新はbuildIdを更新する運用がわかりやすいです。

環境変数を利用したCDN設定

概要

Nuxt.jsではruntimeConfigを環境変数で上書きできます。CDNのURLも実行環境ごとに切り替えられるので、開発環境はローカル、ステージング・本番はCDNに向けると便利です。

設定例（nuxt.config）

export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: '',
    public: { cdnURL: '' }
  }
})

環境変数名は NUXT_API_KEY、NUXT_CDN_URL のように設定します。

環境変数のセット方法

開発: プロジェクトルートに .env を置き NUXT_CDN_URL=https://cdn.dev.example.com
本番: CI/CD の環境変数かサーバーの環境変数に設定

利用例（テンプレート）

<script setup>
const { public: { cdnURL } } = useRuntimeConfig()
</script>
<template>
  <img :src="cdnURL + '/images/logo.png'" alt="logo">
</template>

CSSやfetchのベースURLにも同様に使えます。

注意点

public 配下はクライアント側に公開されます。機密情報は公開にしないでください。環境ごとにURLを切り替えるとデプロイ運用が楽になります。

静的サイト生成（SSG）とCDN配信

概要

Nuxt.jsのSSGは、ビルド時にページをHTMLと静的資産に変換して出力します。nuxt generate（Nuxt3ではnitroの静的出力）を実行すると、配布可能なフォルダが作られ、CDNで高速配信できます。

生成の基本手順

開発環境でルートや動的ルートを定義します。例：/posts/1 のようなページ。
nuxt generate を実行して静的ファイルを作成します。
出力フォルダ（dist や .output/public）をCDNへアップロードします。

CDNへデプロイする際のポイント

アセットの公開パスを合わせる：静的ファイルのURLをCDNドメイン（例: https://cdn.example.com）に変更すると効率よく配信できます。
キャッシュ制御：画像やJSは長め（例: 1年）、HTMLは短めに設定します。
ブラウザキャッシュとCDNキャッシュを分けて考えてください。

動的ルートと生成の注意

事前に知る必要のある動的ルートはgenerateに渡す（設定やスクリプトで一覧化）。
大量ページではインクリメンタル生成や部分的な再ビルドを検討してください。

具体例

S3 + CloudFront：S3にdistを置き、CloudFrontで配信。キャッシュヘッダーはCloudFront側で制御します。
Netlify / Vercel / Cloudflare Pages：ビルドを自動化し、CDN配信までを簡単に設定できます。

SSGとCDNを組み合わせると表示速度が格段に向上します。静的化できる箇所を優先して構築すると運用が楽になります。

WordPressとの連携時のCDN最適化

Nuxt.jsとWordPressをJAMstackで組み合わせる場合、CDNの活用で表示速度とオリジン負荷を大きく下げられます。ここでは実践的な設定と運用のポイントを分かりやすく説明します。

1) キャッシュの分け方

静的資産（CSS/JS/画像）: 長めのTTLを設定します。例: Cache-Control: public, max-age=31536000, immutable
HTML/生成ページ: SSGなら完全にCDNで配信し、SSRや動的部分は短めのTTLやstale-while-revalidateを利用します。例えば max-age=60, stale-while-revalidate=30
認証が必要なAPIやユーザー個別のページはCDNでキャッシュしないか、キャッシュキーで分離します。

2) WordPress REST APIのキャッシュ

APIレスポンスにもCache-ControlやETagを付けてCDNにキャッシュさせます。例: Cache-Control: public, max-age=300
更新時はWebhookでCDNの該当パスをパージします。投稿更新のフックを用意して、該当エンドポイントや一覧を自動で無効化すると確実です。

3) メディアと画像最適化

wp-uploadsをCDN配下にして直接配信します。画像はCDN側で自動リサイズやWebP変換を行うと高速化します。
URLはruntimeConfigで運用ドメインに切り替え、ビルド時も正しいパスを使います。

4) パージと再検証の運用

コンテンツ更新時は部分パージ（URL単位）を基本にします。サイト全体のフルパージは最小限に抑えます。
On-demand revalidation（NuxtのISRに相当）を使うと、必要なページだけ再生成できます。これによりオリジン負荷を抑えながら最新化できます。

5) 注意点

認証付きAPIを誤ってキャッシュすると個人情報が漏れる恐れがあります。必ずヘッダやパスで分離してください。
キャッシュ設定はCDNとWordPress（プラグインやサーバー側）の両方で矛盾がないように確認してください。

これらを組み合わせると、WordPressをヘッドレスにしたときでも高速で安定した配信が可能になります。

Nuxt Contentとの組み合わせ

導入と登録

Nuxt Contentはコンテンツ管理を簡単にするモジュールです。nuxt.config.tsのmodulesに追加して登録します。

export default defineNuxtConfig({
  modules: ['@nuxt/content']
})

CDN設定が効く仕組み

@nuxt/contentで生成した静的コンテンツ（HTMLや画像参照）は、通常のアセットと同様にビルド時やランタイムで参照先を切り替えられます。runtimeConfigでCDNのベースURLを用意し、テンプレートや画像URLに適用すると効率的に配信できます。

具体例（画像の参照）

runtimeConfigにcdnBaseを設定し、コンポーネント内で組み合わせます。

// runtimeConfig.example
public: { cdnBase: 'https://cdn.example.com' }

<img :src="`${useRuntimeConfig().public.cdnBase}/uploads/${image}`" alt="...">

SSGとの相性

generateやnuxt generateで静的ファイルを作る場合、出力時のURLにCDNベースを埋め込めば、静的ホスティングとCDNで高速配信できます。キャッシュ制御やパスの正規化に注意してください。

注意点

コンテンツ内のローカルリンクはビルド時に確認してください。
外部CDNへ切り替えるとCORSやキャッシュが影響します。テストをおすすめします。

ベースディレクトリの動的設定

概要

Nuxt.jsでは環境変数を使ってベースディレクトリを動的に変えられます。CDNやサブディレクトリ配信に対応するときに便利です。ビルド時に異なるパスを指定するだけで、本番用とステージング用で同じビルド設定を使えます。

設定例（Nuxt 2）

const baseDir = process.env.BASE_DIR || '/'
module.exports = {
  router: { base: baseDir },
  build: { publicPath: process.env.ASSET_PATH || '/_nuxt/' }
}

ビルド時に指定する方法

ターミナルで環境変数を渡してビルドします。

BASE_DIR=/blog/ ASSET_PATH=https://cdn.example.com/blog/_nuxt/ npm run build

この手順で生成されるリンクやアセット参照が正しいパスになります。

CDN配信での注意点

静的ファイルの配置とpublicPathを合わせる
ルーティングはビルド時に決まるため、動的な切替は難しい。必要ならHTMLのbaseタグやCDNのリライトを検討してください。

Nuxt 3 のポイント

Nuxt 3ではvite.baseやapp.baseURLを合わせて設定します。runtimeConfigでホスト名だけ切り替える運用が現実的です。

OGP設定とCDN戦略

なぜCDNがOGPで重要か

OGP（og:image、og:url等）は常に絶対URLを参照します。CDNに画像や静的ファイルを置くと配信が速くなり、SNSでの取得も安定します。開発環境と本番でURLを切り替えるため、ベースホストとベースディレクトリを環境変数で管理します。

実装例（Nuxt runtimeConfig）

// nuxt.config
runtimeConfig: {
  public: {
    cdnHost: process.env.CDN_HOST || 'https://example.com',
    cdnBase: process.env.CDN_BASE || '/_assets'
  }
}
// ページで
const cdn = `${useRuntimeConfig().public.cdnHost}${useRuntimeConfig().public.cdnBase}`
ogImage = `${cdn}/og/${imageName}.jpg`