Web アプリを Vercel や Netlify へデプロイするとき、開発（Preview） と 本番（Production） では API エンドポイントや認証キーが異なることが多いです。
初心者がハマりがちなのは、ローカルでは動くのに本番環境でエラーになる「環境変数の差分」を見落としてしまう点です。ここでは、差分管理をシンプルに保つための 5 つのポイントと、GitHub Actions で自動的に切り替える実装例を紹介します。
1. 環境変数ファイルは .env.example だけをリポジトリに残す
実際のキーは GitHub の Secrets に保存し、.env.* ファイルは .gitignore に入れます。
# .gitignore
.env*
2. 環境ごとにプレフィックスを付ける
# .env.preview
NEXT_PUBLIC_API_URL=https://api-preview.example.com
# .env.production
NEXT_PUBLIC_API_URL=https://api.example.com
コード側ではプレフィックスだけで取得できるので、切り替えはファイルの差し替えだけです。
3. CI で環境を判定し、適切なファイルをロード
GitHub Actions の if: 条件で github.ref が refs/heads/main か refs/pull/* かを判定し、dotenv パッケージで読み込みます。
name: Deploy
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set env file
run: |
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
echo "NEXT_PUBLIC_API_URL=${{ secrets.PREVIEW_API_URL }}" >> $GITHUB_ENV
else
echo "NEXT_PUBLIC_API_URL=${{ secrets.PRODUCTION_API_URL }}" >> $GITHUB_ENV
fi
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy to Vercel
uses: amondnet/vercel-action@v20
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-args: "--prod"
env:
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
4. 本番デプロイは必ず --prod フラグで実行
プレビュー環境は自動で作成されますが、--prod を付けないと本番ビルドが走りません。CI の条件分岐でフラグを切り替えるだけで安全です。
5. ローカルでも同様のスクリプトを用意
npm run dev:preview と npm run dev:prod を package.json に定義しておくと、ローカルでも同じ環境変数が使えます。
{
"scripts": {
"dev:preview": "dotenv -e .env.preview next dev",
"dev:prod": "dotenv -e .env.production next dev"
}
}
これらの手順を踏めば、**「ローカルは OK、でも本番で 500 エラー」**という事態を防げます。
環境変数の差分管理は面倒に見えて、実は数行の設定で完結します。ぜひ自分のリポジトリに取り入れて、安心してデプロイを自動化しましょう。