Nuxt の .output ディレクトリとは？〜プロダクションビルドの要〜

Nuxt でアプリケーションをプロダクション用にビルドすると、.output というディレクトリが自動的に生成されます。このフォルダは、ビルド後の成果物をまとめて格納する場所であり、実際のデプロイ時にサーバーやホスティング環境へアップロードする対象となります。

この仕組みがあることで、開発中のソースコードとビルド済みのファイルを明確に分離でき、運用やデプロイの効率化、トラブルシューティングのしやすさが向上します。

まず結論：.output ディレクトリのポイント

• .output は Nuxt のプロダクションビルド成果物を格納する専用フォルダ
• デプロイ時はこのディレクトリの中身をサーバーに配置する
• nuxt build コマンド実行時に毎回再生成されるため、手動での編集は避ける
• .gitignore に追加してリポジトリに含めないのが一般的
• SSR・静的サイト生成（SSG）どちらのモードでも .output は重要な役割を持つ

いつ使うべきか？使わない方がよいケースは？

.output は基本的にプロダクション環境へのデプロイ時に使います。開発中はホットリロードや開発サーバーを使うため、直接触ることはほとんどありません。

使うべきケース

• 本番環境にビルド済みファイルをアップロードする際
• Docker イメージのビルド時に成果物をコピーする場合
• CI/CD パイプラインでビルド成果物をアーティファクトとして扱う場合

使わない方がよいケース

• 開発中に .output 内のファイルを直接編集すること
• .output を Git 管理下に置くこと（ビルド成果物は環境依存のため）
• ビルドコマンドを実行せずに古い .output を使い回すこと（不整合の原因）

実務でよくあるユースケースとサンプルコード

1. Docker コンテナでのデプロイ

Dockerfile で .output をコピーし、Node.js サーバーとして起動する例です。

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY .output .output

EXPOSE 3000

CMD ["node", ".output/server/index.mjs"]

このように .output 配下のサーバーファイルを直接実行して Nuxt アプリを起動します。

2. CI/CD パイプラインでのビルド成果物管理

GitHub Actions や GitLab CI でビルド後に .output をアーティファクトとして保存し、別ジョブでデプロイに利用する例。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: nuxt-output
          path: .output

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: nuxt-output
      - run: rsync -avz .output/ user@server:/var/www/nuxt-app/

3. 静的サイト生成（SSG）での利用

nuxt generate コマンドを使う場合も .output/public に静的ファイルが出力されます。これを CDN や静的ホスティングにアップロードします。

よくある落とし穴・注意点

1. .output の直接編集は厳禁

nuxt build を実行すると .output は毎回クリーンアップされて再生成されます。手動でファイルを編集すると変更が消えてしまうため、ビルド設定やソースコード側で調整しましょう。

2. Git 管理に含めない

.output は環境依存のビルド成果物なので、.gitignore に必ず追加してください。誤ってコミットするとマージコンフリクトや不要な差分が発生します。

3. SSR と CSR の違いに注意

SSR モードでは .output/server にサーバー用のコードが生成され、CSR（クライアントサイドレンダリング）用のファイルは .output/public に配置されます。両者の役割を理解し、適切にデプロイ先を設定しましょう。

4. Hydration エラーの原因に

ビルドと実行環境の不整合（Node.js バージョン違いや依存パッケージの差異）があると、Hydration エラーやレンダリング不具合が起きやすいです。.output はビルド環境と同じ条件で実行することが重要です。

まとめ

.output ディレクトリは Nuxt アプリのプロダクションビルド成果物をまとめる重要なフォルダです。開発中は触らず、ビルド後のデプロイやCI/CDで活用しましょう。Git 管理から除外し、ビルドコマンドで毎回再生成されることを理解することで、安定した運用が可能になります。

適切に .output を扱うことで、Nuxt アプリの本番環境へのデプロイがスムーズになり、トラブルも減らせます。ぜひ実務での運用に役立ててください。