Vercel に Next.js アプリをデプロイするとき、**「どのディレクトリをルートにするか」と「ビルドコマンド・出力ディレクトリの設定」**は意外と見落としがちです。初心者がハマりやすいポイントを順に整理し、正しい設定例をコードとともに紹介します。
1. プロジェクトのルートはどこにすべきか
Vercel はリポジトリの ルート または サブディレクトリ をビルド対象にできます。
-
ルート直下 に
package.jsonがある場合はそのままデプロイ可能。 -
monorepo で複数アプリが混在しているときは、
vercel.jsonのsrcフィールドで対象ディレクトリを指定します。
{
"src": "apps/web", // ← Vercel がここをビルド対象に
"framework": "nextjs"
}
2. ビルドコマンドと出力ディレクトリ
Next.js のデフォルトは
- ビルドコマンド:
next build - 出力ディレクトリ:
.next
Vercel は自動で検知しますが、カスタム設定が必要になるケースがあります。
| ケース | 設定例 |
|---|---|
カスタム npm run build:prod を使う |
Build Command: npm run build:prod |
dist フォルダに出力したい |
Output Directory: dist |
next.config.js で出力先を変えることも可能です。
// next.config.js
module.exports = {
distDir: 'dist', // .next → dist に変更
// 省略可: basePath, assetPrefix など
};
3. 環境変数とシークレットの扱い
Vercel の UI から Environment Variables を設定すると、ビルド時に自動で注入されます。
初心者は「ローカルで dotenv を使う」感覚で、.env.local に書いたものを Vercel にも同様に登録しましょう。
4. デプロイ前にローカルで確認する手順
-
npm run build（または設定したビルドコマンド）でビルドが成功するか -
npm startでローカルサーバーが起動し、期待通りに表示されるか
エラーが出たら、まずローカルで解決してから Vercel にプッシュします。CI として GitHub Actions を組み合わせれば、プルリクエスト時に自動でビルドチェックが走ります。
5. トラブルシューティングのヒント
-
「No Output Directory found」 エラーは
next.config.jsのdistDirが Vercel の設定と食い違っているときに出ます。vercel.jsonのoutputDirectoryと合わせましょう。 -
「Cannot find module '@/components'」 は
jsconfig.jsonのpathsが Vercel に反映されていないケースです。next.config.jsのwebpack設定でエイリアスを明示的に書くと解決します。
// next.config.js のエイリアス例
module.exports = {
webpack(config) {
config.resolve.alias['@'] = path.resolve(__dirname);
return config;
},
};
まとめ
Vercel へのデプロイは「ディレクトリ指定」「ビルドコマンド」「出力ディレクトリ」の3点を正しく合わせるだけでスムーズに進みます。初心者はまずローカルでビルドを成功させ、vercel.json と next.config.js をシンプルに保つことが成功への近道です。