はじめてWranglerでCloudflare Workersをデプロイしてハマったこと

はじめに

以下の記事でWranglerを使ったWorkersの開発・デプロイにチャレンジしてみたのですが、その時に躓いた部分を記録しておきます。

初心者の無知ゆえな内容ですが、同じような方の参考になれば幸いです。有識者の方、ツッコミがあれば是非お願いいたします。

Wrangler概要

WranglerはCloudflare Workersを開発するための公式CLIで、ローカル開発（dev）、設定管理（wranglerファイル）、公開（deploy）などが可能です。2025年12月時点で最新のメジャーバージョンはv4です。

Durable Objectsのクラス定義など、GUIではなくwranglerからの操作でしか行えない設定もあるようです(*)。私がWranglerを使ったきっかけもWorker+Durable Objectsを実装するためでした。

*ダッシュボード画面で設定できなさそう&このあたりのドキュメントの記載からの推察

Before you create and access a Durable Object, its behavior must be defined by an ordinary exported JavaScript class.
https://developers.cloudflare.com/durable-objects/get-started/

Durable Objectsのダッシュボード画面

Wranglerによるデプロイでハマったこと

Wranglerのインストールは問題なくできたのですが、いざデプロイしようとしていくつかハマった部分がありました。

wranglerファイルのフォーマット

Wranglerでは、基本的にwranglerファイルに設定を記述します。従来はwrangler.tomlのみがサポートされていましたが、v3.91.0以降ではJSON形式で記述可能な wrangler.jsonc もサポートされています。現在はwrangler.jsoncの利用が推奨されており、jsonc のみでサポートされる機能も一部あります。

Cloudflare recommends using wrangler.jsonc for new projects, and some newer Wrangler features will only be available to projects using a JSON config file.
https://developers.cloudflare.com/workers/wrangler/configuration/

そのためなのか、init コマンドでプロジェクトを作成すると、デフォルトで wrangler.jsonc が作成されます。私はこの状態で wrangler.toml ファイルを自分で作成して設定を行おうとしていたためハマってしまいました。

2ファイルあると wrangler.jsonc が優先されるようで、wrangler.toml の内容が反映されない状態に…
jsonc を使えば特に問題はないのですが JSON 書くのめんどくさくないですか

wranglerファイルの注意点

• wranglerファイルは基本的に .jsonc を使用する
• .toml を使用する場合、.jsonc の削除が必要

ローカルのコードの変更が反映されない

wranglerファイルやWorkerにデプロイするコード（src/index.js）を変更したら、deploy コマンドを実行することでCloudflare側に反映されます。しかし、deploy コマンドを実行しても明らかに src/index.js の変更が反映されていない時がありました(*)。

原因は分からずなのですが、compatibility_date を変更し、wranglerファイルの変更を検知させてからデプロイさせることで暫定的な対処としています。毎回同じことが発生するわけではなく再現性が低いため、私の環境の不備である可能性がありますが、地味にストレスが…

name = "my-worker"
main = "src/index.js"
compatibility_date = "2022-07-12"

*以下のような状況

• Webページに表示できたテキストの内容だけ変更（→ コードがエラーである可能性は低い）
• リロードしても表示が変更されない。シークレットウィンドウで開いても同じ（→ 変更が反映されてないっぽい）
• deploy コマンドも何回か実行してエラーなし（→ デプロイ忘れでもなさそう）

secretの設定を忘れる

モデルのAPIキーなどはコードに記述せず、secretとして注入することがセキュリティの観点から推奨されます。そのため、ターミナルで secret put を実行して値をセットする必要があるのですが、これを忘れてハマったりしていました。これはハマりどころというより単純なうっかりですね。

secretのセット忘れに関しては、デプロイするコード（src/index.js）側でチェックするようにしないと他に検知する方法がない気がします。ちゃんとコード書きなよという話ですが、個人でサクっと検証する分にはちょっとめんどくさい…
エイリアスなどで deploy コマンドを実行する時に、secret list も実行するようにすればいいのかもしれません。

さいごに

本記事がWranglerでWorker開発にチャレンジする方の参考になれば幸いです。

余談ですが、本記事は 今年新しく触れた技術たち振り返り Advent Calendar 2025 22日目の記事です。当初はAIネタで別のことについて振り返ろうと思っていたのですが、タイムリーに新しく触っていたためwranglerを取り上げさせていただきました。