Contents
📦 環境構築と Nuxt 3 プロジェクトの作成
このセクションでは、Node.js とパッケージマネージャーのインストールから nuxi init によるプロジェクト雛形生成までを順を追って解説します。Nuxt 3 は Node 18 以上 のランタイムと npm (or pnpm) が必須で、バージョンが古いと CLI が起動しないため、最初に環境を正しく整えることが成功の鍵です。
1. Node.js と npm / pnpm のインストール手順
公式サイトから LTS 系 (2024‑2026 年時点では v20) をダウンロードし、インストーラを実行してください。インストール後はターミナルでバージョンを確認します。
|
1 2 3 4 5 6 7 8 |
# Node と npm のバージョン確認 node -v # => v20.x.x npm -v # => 10.x.x (npm が同梱) # pnpm を使いたい場合はグローバルインストール npm i -g pnpm pnpm -v # => 8.x.x |
ポイント：Node 18 以上が必須です。古いバージョンでは
nuxiが「command not found」になるケースがあります【[1] Nuxt Docs – Getting Started】。
2. nuxi init によるプロジェクト生成とディレクトリ構成
以下のコマンドで新規アプリを作ります。my-nuxt-app は任意のフォルダ名に置き換えてください。
|
1 2 3 4 |
npx nuxi init my-nuxt-app # プロジェクト雛形生成 cd my-nuxt-app pnpm install # 依存パッケージをインストール（npm でも可） |
生成されたディレクトリは次のようになります。
| ディレクトリ | 主な役割 |
|---|---|
src/ |
コンポーネント、ページ、スタイル等の実装コード |
src/pages/ |
ファイルベースルーティング（/about.vue → /about） |
src/components/ |
再利用可能な UI 部品 |
nuxt.config.ts |
アプリ全体設定ファイル |
結論：Node とパッケージマネージャーが正しくインストールできたら、nuxi init で生成された構成を把握し、次の SSG 設定フェーズへ進みましょう。
🏗️ 静的サイト生成（SSG）用設定のポイント
Nuxt 3 の静的ビルドは SSR を無効化 (ssr: false) した上で prerender オプションを利用します。従来の target: 'static' は Nuxt 2 用の記述で、Nuxt 3 では削除済みです【[2] Nuxt Docs – Static Site Generation】。正しい設定ができていないとビルド時にサーバー側レンダリングが走り、期待した静的 HTML が出力されません。
1. nuxt.config.ts に SSG 用設定を追加
以下は最小構成の例です。TypeScript 推奨なので defineNuxtConfig を使います。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
// nuxt.config.ts import { defineNuxtConfig } from 'nuxt/config' export default defineNuxtConfig({ // ── SSR 無効化（SSG モード） ──────────────────────── ssr: false, // ── アプリのベース URL （サブディレクトリ展開時に使用） ───── // Nuxt 3 では app.baseURL または runtimeConfig.app.baseURL が推奨 app: { baseURL: '/' // 例: '/my-site/' に変更すると全パスが相対的になる }, // ── プリレンダー設定（静的ページ生成） ─────────────────────── prerender: { crawlLinks: true, // HTML 内のリンクを自動探索 routes: async () => { // 動的に取得したパスを手動追加する例 const { data } = await $fetch<{ slug: string }[]>( 'https://example.com/api/articles' ) return data.map((a) => `/blog/${a.slug}`) } }, // ── ビルド時のエイリアス（@/ の解決） ─────────────────────── alias: { '@': '/src' } }) |
ポイントまとめ
| 設定項目 | 推奨値 / 書式 | 説明 |
|---|---|---|
ssr |
false |
SSR を無効化し、静的生成モードに切り替える |
app.baseURL |
'/' (or '/subdir/') |
サブディレクトリでホスティングする場合のベースパス |
prerender.crawlLinks |
true |
HTML 内リンクを自動的に辿ってページを生成 |
prerender.routes |
関数または配列 | API から取得した動的ルートや手動指定が必要なページ |
2. router.base の代替としての app.baseURL
Nuxt 3 では router.base が非推奨となり、app.baseURL（もしくは runtimeConfig.app.baseURL）で同等の効果を得られます。以下に両者の書き方例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// nuxt.config.ts (静的サイトを /docs/ サブディレクトリへデプロイする場合) export default defineNuxtConfig({ // ランタイム設定から参照したいケース runtimeConfig: { public: { baseURL: '/docs/' } }, app: { // 上記のランタイム変数を直接使用 baseURL: process.env.NUXT_PUBLIC_BASE_URL || '/docs/' } }) |
このように書くと、開発環境・本番環境でベースパスを切り替える のが容易になります。
🔧 ビルド実行・ローカルプレビューとデバッグ
設定が完了したら npm run generate（または pnpm generate）で静的ビルドを走らせます。生成されたファイルは dist/ ディレクトリに出力され、nuxi preview でローカルサーバーとして確認できます。
1. ビルドコマンドと出力結果
以下の手順でビルドし、出力構造を確認してください。
|
1 2 3 |
pnpm run generate # または npm run generate # => ✅ 生成完了: 145 ファイル, 52.3 MB |
dist/ の典型的な構成は次の通りです。
|
1 2 3 4 5 6 7 8 9 10 |
dist/ ├─ index.html # ルートページ ├─ about/index.html # /about → static HTML ├─ blog/ # 動的に生成した記事一覧 │ ├─ first-post/index.html │ └─ second-post/index.html └─ _nuxt/ ├─ assets/ └─ <hashed>.js # ビルドされたクライアントバンドル |
ポイント：index.html がルートに、サブページは同名ディレクトリ配下の index.html として配置されます。これが CDN でのキャッシュ最適化と相性が良い形です。
2. ローカルプレビュー
生成物をローカルで確認するには次のコマンドを実行します。
|
1 2 3 4 |
npx nuxi preview # 静的ファイルをローカルサーバーで提供 # または pnpm run dev --static # 開発モードで静的ビルドをエミュレート |
ブラウザで http://localhost:3000 にアクセスすると、実際のデプロイ環境と同様にページ遷移やリンクが機能することが確認できます。
3. よくあるエラーと対処法
| エラー | 主な原因 | 推奨解決策 |
|---|---|---|
Cannot find module '@/components/…' |
パスエイリアス未設定 | nuxt.config.ts の alias に @: '/src' を追加 |
ReferenceError: process is not defined |
SSR 時に環境変数を直接参照 | runtimeConfig.public.xxx 経由で取得し、クライアント側でも安全に使用 |
404 Not Found（プレビュー） |
ベース URL が不一致 | app.baseURL を正しいサブディレクトリに設定し、再ビルド |
🚀 主要クラウドプラットフォーム別デプロイ設定
静的サイトは dist/ ディレクトリをそのままアップロードできるため、Vercel・Netlify・Cloudflare Pages・Firebase Hosting のいずれでも同様の手順で展開できます。ここではそれぞれのビルドコマンドと公開ディレクトリ設定例に加えて、キャッシュ制御やリライトルールのベストプラクティスも併記します【[4] Nuxt Docs – Deploy】。
1. Vercel (vercel.json)
Vercel はデフォルトで npm run build && npm run generate を実行しますが、明示的に書くと安心です。静的ビルド専用のアダプターは不要です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "builds": [ { "src": "package.json", "use": "@vercel/static-build", "config": { "distDir": "dist" } } ], "routes": [ { "src": "/(.*)", "dest": "/$1.html", "status": 200 } ], "headers": [ { "source": "/**/*.js", "headers": [{ "key": "Cache-Control", "value": "public,max-age=31536000,immutable" }] } ] } |
2. Netlify (netlify.toml)
Netlify の設定はシンプルです。[build] にビルドコマンドと公開ディレクトリを記載し、全ファイルに長期キャッシュヘッダーを付与します。
|
1 2 3 4 5 6 7 8 9 |
[build] command = "npm run generate" publish = "dist" [[headers]] for = "/*" [headers.values] Cache-Control = "public, max-age=31536000, immutable" |
3. Cloudflare Pages (wrangler.toml)
type = "javascript" を指定すると、ビルド後の dist/ が自動的にアップロード対象になります。
|
1 2 3 4 5 6 7 |
name = "my-nuxt-site" type = "javascript" [build] command = "npm run generate" upload_dir = "./dist" |
4. Firebase Hosting (firebase.json)
Firebase のシングルページアプリ向けリライトルールとキャッシュ設定を併せて示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "hosting": { "public": "dist", "ignore": ["firebase.json", "**/.*", "**/node_modules/**"], "rewrites": [{ "source": "**", "destination": "/index.html" }], "headers": [ { "source": "/**/*.js", "headers": [{ "key": "Cache-Control", "value": "public,max-age=31536000,immutable" }] } ] } } |
ベストプラクティス：全プラットフォーム共通で
dist/を公開ディレクトリに指定し、長期キャッシュ (max‑age=1y) を付与すると CDN のパフォーマンスが最大化します。
🤖 CI/CD パイプラインとベストプラクティス
自動化は 品質保証 と デプロイ速度 を同時に向上させます。以下では GitHub Actions と GitLab CI の最小構成を示し、アーティファクト保存・キャッシュ戦略、そしてデプロイ完了後の CDN キャッシュ無効化まで網羅します【[3] Nuxt Docs – CI/CD】。
1. GitHub Actions（Vercel デプロイ例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
name: Deploy Nuxt 3 SSG to Vercel on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '20' cache: 'pnpm' # pnpm のキャッシュを自動保存 - name: Install dependencies run: pnpm install --frozen-lockfile - name: Generate static site run: pnpm generate - name: Upload generated files as artifact uses: actions/upload-artifact@v4 with: name: dist path: dist/ - name: Deploy to Vercel (production) uses: amondnet/vercel-action@v20 env: VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }} VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} with: vercel-args: '--prod' |
- キャッシュ戦略：
setup-nodeのcache: pnpmによりnode_modules/.pnpm-storeが再利用され、ビルド時間が 30 % 前後短縮します。 - アーティファクト：
dist/を一度保存しておくことで、別ジョブでのデプロイや手動ダウンロードが容易になります。
2. GitLab CI（GitLab Pages 用）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
image: node:20-alpine stages: - build - deploy cache: paths: - node_modules/ build_static: stage: build script: - pnpm install --frozen-lockfile - pnpm generate artifacts: paths: - dist/ expire_in: 1 week pages: stage: deploy script: - echo "Deploying to GitLab Pages" artifacts: paths: - dist/ |
- アーティファクトは
build_staticジョブからpagesジョブへ自動的に受け渡されます。 - キャッシュは
node_modules/を保持し、パイプラインの実行コストを削減します。
3. CDN キャッシュ無効化（例：Vercel）
デプロイ完了後に Vercel の API を呼び出すだけでキャッシュが自動リフレッシュされます。GitHub Actions に以下のステップを追加すると、手作業不要です。
|
1 2 3 4 5 6 |
- name: Purge Vercel CDN cache run: | curl -X POST "https://api.vercel.com/v2/projects/${{ secrets.VERCEL_PROJECT_ID }}/domains" \ -H "Authorization: Bearer ${{ secrets.VERCEL_TOKEN }}" \ -d '{"purgeAll":true}' |
📚 まとめ
- 環境構築：Node 18+ と npm/pnpm をインストールし、
nuxi initで Nuxt 3 プロジェクトを作成。 - SSG 設定：
ssr: falseに加えてapp.baseURL（またはruntimeConfig.app.baseURL）とprerenderを正しく記述することで、完全な静的サイトが生成できる。 - ビルド & プレビュー：
pnpm generate→dist/が作成され、nuxi previewでローカル確認可能。エラーはエイリアス・環境変数の扱いに注意。 - デプロイ先別設定：Vercel、Netlify、Cloudflare Pages、Firebase Hosting のすべてが
dist/をそのまま公開できる。キャッシュヘッダーを長期に設定すると CDN 効果が最大化する。 - CI/CD：GitHub Actions と GitLab CI のテンプレートで自動ビルド・アーティファクト保存・デプロイまで一貫したフローを構築できる。キャッシュ戦略と CDN 無効化を組み合わせれば、リリースサイクルが大幅に短縮する。
これらの手順を踏めば、Nuxt 3 の静的サイト生成から本番デプロイまで、一貫した開発フローを実現できます。ぜひローカルで pnpm generate を試し、GitHub リポジトリにプッシュして CI が走る様子をご確認ください。
参考情報（出典）
| 番号 | タイトル・リンク |
|---|---|
| [1] | Nuxt 3 – Getting Started https://nuxt.com/docs/getting-started/installation |
| [2] | Nuxt 3 – Static Site Generation (SSG) https://nuxt.com/docs/guide/concepts/static-site-generation |
| [3] | Nuxt 3 – Deploy & CI/CD https://nuxt.com/docs/getting-started/deployment#ci-cd |
| [4] | Nuxt 3 – Deployment Guides (Vercel, Netlify, Cloudflare Pages, Firebase) https://nuxt.com/docs/getting-started/deployment |