Nuxtでcdnのurl設定を徹底解説！メリットと注意点を詳しく紹介

2025 10/31

2025/10/31

はじめに

目的

本ドキュメントは、Nuxt.jsアプリケーションで静的アセット（画像、CSS、JavaScriptなど）をCDNで配信する際の考え方と設定方法を分かりやすくまとめたものです。cdnURLの基本的な使い方に加え、baseURLやbuildAssetsDirとの違い、SEOや運用時の注意点も扱います。

対象読者

Nuxt.jsでサイトやアプリを作っているエンジニアや運用担当者向けです。初心者にも分かるように専門用語は最小限にし、具体例を交えて説明します。経験が浅くても読み進められます。

前提条件

Nuxt.jsのプロジェクト構造や基本的なビルド手順（npm/yarnによるビルド）がわかっているとスムーズです。CDNの仕組み全体を知らなくても理解できるように説明します。

本書の読み方

第2章以降で目的や設定方法、実例、SEOやトラブル対応まで順に解説します。まずは全体像をつかみ、必要な章に戻って設定や検証を行ってください。テスト環境で動作確認を行うことを推奨します。

Nuxt.jsでのCDN利用目的とメリット

目的

Nuxt.jsでCDNを使う主な目的は、画像やCSS・JavaScriptなどの静的ファイルをユーザーの近くから配信し、表示を速くすることです。もう一つの目的は、自分のサーバーへの負荷を減らし、安定した表示を保つことです。具体的には、世界中の利用者に対して遅延を下げ、表示崩れやタイムアウトを防ぎます。

主なメリット

表示速度の向上：CDNは地理的に近いサーバーから配信するため、読み込みが速くなります。たとえば日本のユーザーは国内のエッジで受け取れます。
サーバー負荷の分散：静的アセットのリクエストをCDNに渡すことで、オリジンサーバーの負担が軽くなります。
可用性の向上：CDNは冗長性を持つため、一部サーバー障害でも配信を維持しやすいです。
コストとキャッシュ効果：頻繁に使われるファイルはCDNにキャッシュされ、転送コスト削減や応答速度の改善が期待できます。

具体例

画像URLをhttps://cdn.example.com/images/…に置き、HTMLやCSSから参照する。
ビルド生成後のdist/staticや/_nuxt/配下のファイルをCDN経由で配信する。

いつ使うべきか

アクセスが多いサイト、グローバルなユーザー層、大きな画像や動画を扱う場合は早めに導入すると効果が出ます。ローカルやテスト環境では不要な場合が多いです。

CDN設定の基本—cdnURLオプション

cdnURLとは

NuxtのcdnURLは、本番環境で静的アセット（画像やJS/CSSなど）を配信するための絶対URLを指定する設定です。CDNにアップロードしたファイルを指すことで、ブラウザにはCDNドメイン経由でファイルが配信されます。

設定例

export default defineNuxtConfig({
  app: {
    cdnURL: 'https://your-cdn-domain.com/',
  },
})

ポイントは絶対URLを指定し、末尾にスラッシュを付けるとパス結合での誤解が減ります。

動作のイメージ

ビルド時に生成される静的ファイルの参照先がCDNのURLに置き換わります。例えば、ビルド後の/nuxt-assets/logo.pngへの参照は
https://your-cdn-domain.com/nuxt-assets/logo.png のようになります。これは本番配信時のみ有効です。

実務上の注意点

本番環境専用です。ローカル開発では空文字のままにして動作確認してください。
ビルド時に設定します。実行時に動的に切り替えることは推奨されません。
CDN側でCORSやHTTPSが正しく設定されているか確認してください。
ファイル名にハッシュを使えばキャッシュ更新が楽になります。

これらを整えると、配信速度向上や負荷分散の恩恵を受けやすくなります。

nuxt.configでのCDN設定例と注意点

設定例

export default defineNuxtConfig({
  app: {
    cdnURL: 'https://your-cdn.com/',
    buildAssetsDir: '/_nuxt/',
  },
})

上記で静的アセットは https://your-cdn.com/_nuxt/ から配信されます。

主なポイント

cdnURLは末尾にスラッシュを付けてください。パス結合ミスを防げます。
buildAssetsDirはビルド時の出力パスです。CDN上の設置先と一致させます。

注意点

CDNへアップロードしたファイル名とURLが厳密に一致する必要があります。CI/CDや自動アップロードを使うとミスを減らせます。
本番環境のみcdnURLを設定し、ローカル開発は空にしておくのが一般的です。
キャッシュ対策（ファイル名にハッシュを付ける、CDNの無効化）は必ず検討してください。

デプロイ時の運用

ビルドして生成された静的ファイルをCDNにアップロードします。
アップロード後、CDNのキャッシュを必要に応じてinvalidateします。
自動化パイプラインでバージョン管理と一致させると安全です。

これらを守ることで、静的アセットの配信が安定します。

SEOやその他の関連設定

概要

CDN化は表示速度を上げますが、SEOにも影響します。ページ本体のURL、画像やOGPのURL、サイトマップなどをどう扱うかを整理するとよいです。

サイトURL（site.url）とcanonical

site.urlは検索エンジンにとっての正規ドメインを指します。通常は公開サイトのドメインを指定してください。資産（画像・CSSなど）はCDNで配信しても、canonicalはオリジナルのサイトURLにします。

OGP／Twitter／構造化データ

OGPやTwitter Cardのimageは絶対URLにしてください。表示速度向上のため画像はCDNのURLにして問題ありませんが、metaで指定するURLは正確に絶対パスにしてください。

sitemap・robots

サイトマップはsite.urlに基づく完全なページURLを出力します。sitemap内の画像URLをCDNにする設定がある場合はそれを利用します。robots.txtはCDN側と本体の両方で不要なクロールを防ぐよう設定してください。

headでの追加リソース

link rel=preconnectやdns-prefetchでCDNを事前接続すると効果的です。フォントやCORSが必要な資産にはcrossorigin属性を付けてください。

注意点

CDNドメインをそのままsite.urlにしてしまうと検索結果の表示に影響する可能性があります。資産配信はCDN、ページの正規ドメインはsite.urlで分ける運用をおすすめします。

設定時のトラブル・注意事項

よくある設定ミスと対処法

末尾スラッシュの扱い：cdnURLが「https://cdn.example.com/」か「https://cdn.example.com」で異なる挙動になります。パス連結でスラッシュが二重になったり欠けたりすると、期待どおりのURLになりません。対処例：

const normalize = url => url.replace(/\/+$|^\/+/g, '')
const assetUrl = normalize(cdnURL) + '/_nuxt/app.js'

URL不一致：環境ごとにCDN URLを切り替え忘れると本番で404になります。環境変数で明示的に管理してください。

キャッシュとパス整合性

キャッシュ設定を確認してください。古いファイルが残ると見た目が更新されません。ファイル名にハッシュを付ける（fingerprinting）か、CDNで適切にinvalidate（無効化）します。
パス一致も重要です。ビルド出力のディレクトリ名（例：/_nuxt/や/assets/）とCDN上のパスが一致しているか確認します。