Next.jsで `basePath` を `/homepage2` にして S3 へ静的デプロイする

2025-10-15

要約（TL;DR）：next.config.mjs に basePath:'/homepage2' を指定し、静的出力向けのオプション（assetPrefix、output:'export'、trailingSlash、images.unoptimized）をセット。pnpm build && pnpm exec next export で out/ を生成し、aws s3 sync で s3://{bucket}/homepage2/ へアップロード。S3静的ホスティングで Index/404 を設定すればOK。画像や fetch の絶対パスは basePath に合わせて修正。

1. 前提とゴール

Next.js 14+（App Router/Pages RouterどちらでもOK）
公開URL配下を /homepage2 にしたい（サブディレクトリ運用）
AWS S3 の静的ウェブサイトホスティングで配信
（任意）今後 CloudFront を挟んでも破綻しない設計

2. `next.config.mjs` の設定

/** @type {import('next').NextConfig} */
export default {
  basePath: '/homepage2',
  assetPrefix: '/homepage2/',        // サブディレクトリ配信の静的サイトでは実質必須
  output: 'export',                // 静的エクスポート
  trailingSlash: true,             // S3 では末尾スラッシュ運用が安全
  images: { unoptimized: true },   // next/image を静的化
};

ポイント： basePath はアプリのルートを /homepage2 にシフトします。assetPrefix を合わせて指定すると、ビルド済み静的アセット（_next/static など）も /homepage2 配下で参照され、S3のサブディレクトリ運用と噛み合います。

3. コード側の注意（リンク・画像・fetch）

リンク： next/link を使えば自動で /homepage2 が付与されるので、<Link href="/about"> のように 素直にルートから 書く（/homepage2/about と手書きしない）。

画像： next/image を推奨。もし生の <img src="/logo.png"> を使うなら basePath を付与する。

import { useRouter } from 'next/router';
const { basePath } = useRouter();
// 例:
<img src={`${basePath}/logo.png`} alt="logo" />

fetch： ブラウザ側の fetch('/api/xxx') は basePath が付かずドメイン直下を指すためNG。

import { useRouter } from 'next/router';
const { basePath } = useRouter();
await fetch(`${basePath}/api/hello`);

4. ビルド & 静的エクスポート

pnpm build
pnpm exec next export -o out

生成物は out/ 直下に index.html（および各ページの /path/index.html）が並び、参照パスは /homepage2 前提で吐き出されます。

5. S3 に配置（`homepage2/` プレフィックス）

バケット例：my-site-bucket。S3 上では homepage2/ フォルダに静的ファイルを置きます。

aws s3 sync ./out/ s3://my-site-bucket/homepage2/ --delete

6. S3 静的ウェブサイトホスティング設定

バケットの「静的ウェブサイトホスティング」を有効化
インデックスドキュメント：index.html
エラードキュメント：index.html（SPAルーティングを維持したい場合）

公開URL例：http://<bucket>.s3-website-<region>.amazonaws.com/homepage2/

補足： サブディレクトリ単位で 404 => /homepage2/index.html にリダイレクトしたい場合は、S3の「ルーティングルール」で /homepage2/* を /homepage2/index.html に流すルールを追加すると堅牢です。

7. 公開（パブリックアクセス）とキャッシュ

S3直公開ならオブジェクトのパブリックリードが必要です（バケットポリシー or ACL）。継続運用では、_next/static は長めのキャッシュ、それ以外は短め/無効化などの使い分けが有効です：

# ビルド済み静的アセットは長めに
aws s3 cp out/_next/ s3://my-site-bucket/homepage2/_next/   --recursive --cache-control "public,max-age=31536000,immutable"

# HTMLは即時反映を優先
aws s3 cp out/ s3://my-site-bucket/homepage2/   --recursive --exclude "_next/*" --cache-control "no-store"

8. SEO のポイント（サブディレクトリ運用時）

canonical：サブディレクトリ込みで正規URLを指定（例：https://example.com/homepage2/xxx）。

サイトマップ：next-sitemap を使うなら siteUrl を https://example.com/homepage2 に、出力先パスも考慮。

// next-sitemap.config.js
module.exports = {
  siteUrl: 'https://example.com/homepage2',
  generateRobotsTxt: true,
  outDir: 'out', // next export と揃える
  transform: async (config, path) => {
    // 追加のメタや優先度調整があればここで
    return {
      loc: path,
      changefreq: 'weekly',
      priority: 0.7,
      lastmod: new Date().toISOString(),
      alternateRefs: [],
    };
  },
};

Open Graph/Twitterカード：OG画像などのURLも /homepage2 を含む絶対URLに。
内部リンク：next/link を使い、/homepage2 を手書きしない（重複で /homepage2/homepage2/... にならないように）。

9. よくある落とし穴チェックリスト

❌ <Link href="/homepage2/about"> と書いて二重化 → ✅ href="/about"
❌ <img src="/logo.png">（basePath未反映） → ✅ src={`${basePath}/logo.png`} か next/image
❌ fetch('/api/foo')（basePath未反映） → ✅ fetch(`${basePath}/api/foo`)
❌ trailingSlash 未設定で S3 の /path 直アクセスが 404 → ✅ trailingSlash:true
❌ 404 が SPA で拾えない → ✅ S3 のエラードキュメントを index.html に

10. 検証手順（ローカル & 本番）

ローカル：pnpm dev で http://localhost:3000/homepage2 を確認（devサーバ再起動を忘れない）。
本番：pnpm build && pnpm exec next export -o out → aws s3 sync → S3ウェブサイトURLで /homepage2/ を確認。
画像・リンク・動的遷移・404動作・OGカードを確認。

11. 運用を楽にする `package.json` スクリプト例

{
  "scripts": {
    "build:static": "next build && next export -o out",
    "deploy:s3": "aws s3 sync ./out/ s3://my-site-bucket/homepage2/ --delete",
    "deploy:s3:fast": "pnpm build:static && pnpm deploy:s3"
  }
}

12. まとめ

basePath を /homepage2 に設定し、静的エクスポート + S3 配置の基本を押さえれば、サブディレクトリ運用でもシンプルに公開できます。