プロフィール

arismmn timeline blog

← ブログ一覧に戻る
2026年02月21日（土）

Cloudflare Pagesで環境変数を設定したら必ずデプロイが必要な理由

Cloudflareデプロイインフラ

📝 はじめに

Cloudflare Pagesで開発していて、環境変数を設定したのに反映されない...そんな経験はありませんか？

今日、管理画面からSlack通知を送る機能を実装していたところ、EVENT_WORKER_BOT_TOKENとSLACK_REPORT_CHANNELという環境変数が未設定だったことに気づきました。

Cloudflare Dashboardから環境変数を追加したものの、「次回のデプロイ時から有効になります」というメッセージが表示され、**コードを変更していないのにデプロイが必要なの？**と疑問に思いました。

この記事では、その理由と具体的な対処方法を解説します。

🔍 問題の症状

実装した機能

管理画面（admin-dashboard.astro）でイベントの目標値を変更した際、Slackの#eventチャンネルに軍師botから通知を送信する機能を実装しました。

// webapp/src/pages/admin/admin-dashboard.astro (抜粋)
if (previousGoal !== 0 && previousGoal !== newGoal) {
  const token = runtime.env.EVENT_WORKER_BOT_TOKEN;        // 軍師botのトークン
  const channel = runtime.env.SLACK_REPORT_CHANNEL;  // #eventチャンネルのID
  
  if (token && channel) {
    await fetch('https://slack.com/api/chat.postMessage', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        channel: channel,
        attachments: [{
          color: "#3498db",
          text: `⚔️ *軍師の進言* ⚔️\n\nお嬢様！目標値が変更されましたぞ！...`,
          // ... 省略
        }]
      })
    });
  }
}

発生した問題

  1. コードをデプロイして、管理画面で目標値を変更
  2. Slack通知が届かない
  3. ログを確認したらtokenとchannelがundefined
  4. あ！環境変数を設定していなかった...

環境変数を追加

Cloudflare Dashboardから環境変数を追加：

  • Workers & Pages → webapp → Settings → Environment variables
  • Productionタブで以下を追加：
    • EVENT_WORKER_BOT_TOKEN: xoxb-...（Encrypt チェック）
    • SLACK_REPORT_CHANNEL: C0AG1Q83WDN（平文）

追加すると、こんなメッセージが表示されます：

✅ Environment variable added successfully.
⚠️ Changes will take effect on the next deployment.

「次回のデプロイ時から」って、コード変更してないのにデプロイが必要なの...？🤔

💡 なぜ再デプロイが必要なのか

Cloudflare Pagesのデプロイの仕組み

Cloudflare Pagesは以下のプロセスでアプリケーションをデプロイします：

1. ソースコード取得（Git連携）
   ↓
2. **環境変数を読み込み**
   ↓
3. ビルド実行（npm run build）
   ↓
4. 静的ファイル生成
   ↓
5. Cloudflare Workers runtime に配置
   ↓
6. 実行環境に環境変数を注入

重要なポイント：

  • 環境変数はデプロイ時に読み込まれる
  • すでにデプロイされている実行環境には、新しい環境変数が反映されない
  • 環境変数を追加・変更した場合、必ず再デプロイが必要

具体例で理解する

最初のデプロイ（環境変数なし）

// デプロイ時に読み込まれた環境変数
{
  DB: D1Database,
  BASIC_AUTH_USER: "admin",
  // EVENT_WORKER_BOT_TOKEN: 存在しない
  // SLACK_REPORT_CHANNEL: 存在しない
}

この状態でアプリが動いているため、runtime.env.EVENT_WORKER_BOT_TOKENはundefinedのままです。

Dashboardで環境変数を追加

環境変数の設定情報がCloudflareのデータベースに保存されますが、既存のデプロイには影響しません。

再デプロイ後

// 新しいデプロイで読み込まれた環境変数
{
  DB: D1Database,
  BASIC_AUTH_USER: "admin",
  EVENT_WORKER_BOT_TOKEN: "xoxb-...", // ✅ 追加された！
  SLACK_REPORT_CHANNEL: "C0AG1Q83WDN" // ✅ 追加された！
}

これで初めてruntime.env.EVENT_WORKER_BOT_TOKENが利用可能になります。

🛠️ 解決方法：2つの再デプロイ方法

コードを変更していなくても、環境変数を反映させるために再デプロイが必要です。

方法A：Cloudflare Dashboardからリトライ（推奨）

最も簡単で推奨される方法です。

  1. Cloudflare Dashboard → Workers & Pages → webapp
  2. Deployments タブを開く
  3. 最新のデプロイ（一番上）をクリック
  4. Retry deployment ボタンをクリック

これだけで、同じコミットが新しい環境変数とともに再デプロイされます。

メリット：

  • ✅ 操作が簡単（ブラウザだけで完結）
  • ✅ Gitの履歴を汚さない
  • ✅ 「環境変数のみ変更、コードは変更なし」という意図が明確

使い所：

  • 環境変数の追加・変更のみ
  • 既存のデプロイに問題がなく、環境変数だけ反映したい場合

方法B：空コミットでgit push

Gitから自動デプロイしたい場合の方法です。

# プロジェクトディレクトリに移動
cd webapp

# 空コミット（ファイル変更なし）を作成
git commit --allow-empty -m "chore: 環境変数反映のための空コミット"

# リモートにプッシュ
git push origin main

Cloudflare Pagesが新しいコミットを検知し、自動的に再デプロイが開始されます。

メリット：

  • ✅ Gitの履歴に記録が残る
  • ✅ 自動デプロイのトリガーとして機能
  • ✅ CI/CDパイプラインと統合できる

デメリット：

  • ⚠️ 実質的な変更がないコミットがGit履歴に残る
  • ⚠️ ターミナル操作が必要

使い所：

  • Git履歴に「このタイミングで環境変数を変更した」と記録したい場合
  • CI/CDパイプラインから再デプロイを実行したい場合

📊 Production vs Preview環境

Cloudflare Pagesでは、環境変数をProductionとPreviewで個別に管理できます。

Production環境

  • mainブランチへのプッシュでデプロイ
  • 本番サイト（例：myapp.pages.dev）
  • 本番用の環境変数を設定

Preview環境

  • 他のブランチへのプッシュでデプロイ
  • プレビューサイト（例：feature-xyz.myapp.pages.dev）
  • 開発/テスト用の環境変数を設定

環境変数設定時の注意点：

  • Production/Previewのどちらに設定するか選択できる
  • 両方に同じ変数名で異なる値を設定可能
  • 例：Preview環境では開発用のSlackチャンネルを使う

🔐 環境変数の種類：平文 vs Secret

平文（Plaintext）

チェックなしで保存した環境変数は、Dashboardで再度確認できます。

使い所：

  • チャンネルID（例：SLACK_REPORT_CHANNEL）
  • 公開されても問題ない設定値
  • デバッグ時に確認が必要な値

Secret（Encrypted）

Encrypt チェックを入れて保存した環境変数は、暗号化されて保存され、Dashboardでも確認できません。

使い所：

  • APIトークン（例：EVENT_WORKER_BOT_TOKEN）
  • パスワード
  • 秘密鍵

重要： 一度Secretとして保存すると、Dashboardで値を確認できません。忘れた場合は再設定が必要です。

✅ 実装の成功例

今回の実装では、以下のように設定しました：

環境変数の設定

変数名 値 タイプ 用途
EVENT_WORKER_BOT_TOKEN xoxb-... Secret Slack APIの認証トークン
SLACK_REPORT_CHANNEL C0AG1Q83WDN 平文 #eventチャンネルのID

再デプロイ実行

Cloudflare Dashboard → Deployments → Retry deployment

検証

  1. 管理画面（/admin/dashboard）でイベントの目標値を変更
  2. Slackの#eventチャンネルを確認
  3. ✅ 軍師botから「⚔️ 軍師の進言 ⚔️」通知が届いた！

🎓 学んだこと

❌ 誤解していたこと

  • 「環境変数を追加したら即座に反映される」
  • 「Cloudflare Pagesはサーバーレスだから、設定変更も即反映されるはず」

✅ 正しい理解

  • 環境変数はデプロイ時に読み込まれる
  • 既存のデプロイには反映されない
  • 環境変数を追加・変更したら、必ず再デプロイが必要
  • Dashboardの「Retry deployment」が最も簡単

💡 今後のベストプラクティス

  1. 環境変数を追加したら即座に再デプロイ

    • 「後でデプロイしよう」と忘れて、動かない原因になる

  2. Dashboardから確認する習慣

    • Workers & Pages → Settings → Environment variables
    • 設定済みの環境変数を一覧で確認
    • 重複や設定ミスを防げる

  3. 環境変数の命名規則を統一

    • SLACK_*: Slack関連
    • *_CHANNEL: チャンネルID（平文）
    • *_TOKEN: トークン（Secret）
    • *_SECRET: シークレット（Secret）

  4. ドキュメントに記録

    • .github/copilot-instructions.mdに環境変数の一覧を記載
    • 新しい機能を実装する際、必要な環境変数を明記

🔗 関連リソース

公式ドキュメント

プロジェクト内の関連ドキュメント

📝 まとめ

Cloudflare Pagesで環境変数を追加・変更した際は：

  1. 必ず再デプロイが必要
  2. Dashboardの「Retry deployment」が最も簡単（推奨）
  3. Git履歴に残したい場合は空コミット
  4. Secret（暗号化）と平文を適切に使い分ける
  5. Production/Preview環境を個別に管理できる

この記事が、同じ疑問を持った方の助けになれば幸いです！

執筆日: 2026年2月21日
カテゴリ: Cloudflare, デプロイ, インフラ
関連タグ: #CloudflarePages #環境変数 #デプロイ #トラブルシューティング

Gemini
Powered by
Gemini
(使用モデル Gemini3)
← ブログ一覧に戻る