実験レポート: examples/blog を TinyGo で Cloudflare Workers に載せる #

pkg/* と go:embed #

• tinygo test ./pkg/... は 4 パッケージとも成功した。
• go:embed は、examples/blog の記事・favicon も、ルートパッケージの sandbox.Docs（TODO.md と docs/）も、TinyGo の wasm でそのまま読めた（/docs/TODO などが表示される）。

そのままではビルドできない: os.OpenRoot #

examples/blog/repo.go:37:15: undefined: os.OpenRoot

-debug でファイルを読むときの os.Root が TinyGo にはない。Workers には関係のない機能なので、Workers 用のビルドから外す。

TinyGo の ServeMux は古い #

TinyGo の net/http は標準ライブラリの複製に手を入れたもので、ServeMux は Go 1.22 より前の実装に、{x} だけを扱う独自のマッチを足したものだった。同じパターンを登録したときの結果:

examples/blog は GET /{$}、GET /posts/{slug}、GET /docs/{path...} を使っていたので、全ページが 404 になった。

対応として、ServeMux をやめて server.route で手書きで振り分けるようにした。パスの値は r.SetPathValue で入れるので、各ハンドラは変えずに済む。ServeMux がしていた次の挙動も合わせて実装し、テストを足した。

• GET と HEAD 以外は 404 ページ（以前も / のパターンが拾って 404 になっていた）
• /docs → /docs/ へのリダイレクト
• .、..、連続するスラッシュを含むパスを、正規化したパスへリダイレクト（307）

標準 Go のビルドでは ServeMux のまま、TinyGo のビルドだけ手書きにする案もあるが、ルーティングが二重になるので採らなかった。

workers-go の実行モデル #

workers-assets-gen が生成する worker.mjs は、fetch のたびに new Go() と new WebAssembly.Instance(...) を作り、go.run で **main を実行する**。コンパイル済みのモジュールは使い回されるが、Go のヒープはインスタンスごとなので、リクエストのたびにまっさらな状態から始まる。

Cloudflare Workers 自体は isolate を複数のリクエストで使い回し、JS ならモジュールスコープの変数がリクエストをまたいで残る。毎回やり直しになるのはプラットフォームの制約ではなく、workers-go の設計による。

• 環境変数（cloudflare.Getenv）は main の中から読める。-base-url の代わりに、wrangler.jsonc の vars.BASE_URL から読むようにした。
• sync.Once やグローバル変数でキャッシュしても、次のリクエストには残らない。

ローカルの wrangler dev での応答時間は、TinyGo で 3〜10ms、標準 Go で 5〜8ms ほどだった。

リクエストごとに全記事をパースしている理由 #

どのページへのリクエストでも、全記事と全ドキュメントをパースしている。原因は次の 2 つの組み合わせ。

1. **コードの作り（主因）**: main は起動時に全記事と全ドキュメントを読み込み、パースしてメモリに持つ。examples/blog は長く動き続けるサーバーを前提にしているので、起動時に一度だけ払うこのコストは問題にならなかった。main_workers.go も同じ起動手順を流用している。 2. **workers-go の実行モデル**: 上のとおり main がリクエストごとに走るので、「起動時に一度だけ」が「毎回」になる。

go:embed は関係ない。埋め込んだファイルは wasm のデータセグメントに入っていて、インスタンス化のときにメモリへコピーされるだけで、パースはされない。

ページごとに本当に必要なものは次のとおりで、記事ページやドキュメントのページなら 1 本だけで済む。

一覧ページは、タイトルや説明を front matter がなければ本文の最初の見出しや段落から取るので、作り方を変えても全記事のパースが要る。

今のコストは小さい。ネイティブのベンチマークで、全記事（3 本）と全ドキュメント（4 本）の読み込みは 1 回あたり約 32µs、131 KB、718 allocs だった。wasm では数倍遅いとしても 1ms に届かない。ただし記事の数に比例して増える。

必要になったときの対策の候補:

1. **ルートに応じて遅延ロードする**: 記事ページでは、ファイル名の一覧（パース不要）から該当する 1 本だけを読んでパースする。一覧ページは全件パースのまま。 2. **ビルド時にメタデータを作る**: go generate でタイトル・日付・説明の索引を作って埋め込めば、一覧ページもパースが要らなくなる。 3. **インスタンスを使い回す worker.mjs を自前で書く**: 効果は一番大きいが、workers-go の生成物から外れるのでおすすめしない。

バイナリサイズと Workers のサイズ制限 #

2026-09-04 の changelog で、Workers のサイズ制限は「非圧縮で 64 MiB（全プラン共通）、圧縮後のサイズは無制限」になった（以前は圧縮後で Free 3 MB、Paid 10 MB）。標準 Go のビルドも十分に収まるので、**サイズ制限はもう TinyGo を選ぶ決め手にならない**。標準 Go の wasm も wrangler dev で同じように動いた。

なお、この wasm がブラウザに送られることはない。wasm は Cloudflare のエッジ（サーバー側）で動き、ブラウザが受け取るのは SSR された HTML だけ（一覧 / は 1,464 B、記事 /posts/hello は 1,682 B、最大の /docs/sketch/ja/blog でも 18,005 B）。wasm がアップロードされるのは wrangler deploy のときだけ。

サイズが効くのはサーバー側のコストのほう:

• コールドスタート: エッジが Worker を読み込むときに wasm をコンパイルする。ここは wasm が大きいほど遅くなるはずなので、標準 Go（8.2 MiB）より TinyGo（2.0 MiB）が有利。サイズ制限がなくなっても、TinyGo を選ぶ理由はここに残る。
• リクエストごと: コンパイル済みのモジュールは使い回されるが、インスタンスの生成、Go ランタイムの初期化、main（全記事のパース）は毎回走る（「workers-go の実行モデル」を参照）。

どちらも本番での計測はしていない。

このため、ビルドタグは tinygo ではなく js && wasm にした。TinyGo の -target wasm は GOOS=js GOARCH=wasm になるので、どちらのコンパイラでも同じファイルが選ばれる。

テスト #

• 標準 Go の go test は、どちらの案でも今までどおり通る。
• GOOS=js GOARCH=wasm go test（node で実行）は、workers-go を import したパッケージでは失敗する。workers-go の init が Workers の JS グローバルを参照して panic するため。
• tinygo test -target wasm は、TinyGo の Docker イメージに node がないため試していない。
• native の tinygo test では、httptest.NewServer に接続できず（connection refused）、Close で止まった。この現象が出るのは -watch の SSE テスト（TestLiveReloadEvents）だけで、TinyGo では skip するようにした（案 B）。

replace ではなく go.work を使う場合 #

examples/blog/workers/go.mod の require + replace ../../.. の代わりに、ルートに go.work（use . と use ./examples/blog/workers）を置く形も試した。

• go.work があれば、workers/go.mod からルートモジュールの require を消しても、go build と tinygo build の両方が通る。ルートで go test ./...／go vet ./... を実行しても、workers のパッケージは対象にならない（go list ./... で確認）。
• require を残して replace だけを消すと、go.work があっても v0.0.0 を取りに行って失敗した。
• go.work がないとき（GOWORK=off、または clone した直後）はビルドできない。.gitignore が go.work を無視しているので、コミットしない運用とは合わない。
• go mod tidy は go.work を見ないので、workers で実行すると proxy から公開済みのルートモジュールを取ってきて、internal/site がないと言って失敗する。

このため replace を残すのがよい。replace があれば、モジュール単体で go mod tidy もビルドも完結する。エディタ（gopls）で両方のモジュールをまとめて開きたいときに、各自が手元で go.work を作る（ignore されたまま）のは、replace と併用しても問題ない。

examples/blog-tiny（兄弟）ではなく examples/blog/workers（入れ子）にする理由 #

• 兄弟の examples/blog-tiny からは examples/blog/internal/... を import できない。共有部分を examples/internal/... に移すか、internal でない公開パッケージにする必要がある。入れ子にすれば、ブログに関係するものを examples/blog の下にまとめたまま internal を使える。
• -watch や -debug などのフラグは Workers 側には要らない。この「フラグなしの別エントリポイント」という性格は、どちらに置いても同じ。
• 名前を tiny にしなかったのは、上で書いたとおり標準 Go でもビルドできて、TinyGo 専用ではないから。中身を表すのは「Workers で動かす」こと。