# 手元では動くのに、配ると壊れる：このサイトで起きた四つの事故

> 古いキャッシュ、組むたびに増えるパンくず、環境の中を指す symlink、手元にしか無い絵。サイトを配るときに続いた四つの事故と、検査を足してはじめて見つかった経緯。

- URL: https://koshinstudio.com/notes/deploy-gotchas/
- 公開: 2026-10-08
- 書いた人: Koshin（https://koshinstudio.com/about/）
- サイト: Koshin Studio

  English version (https://koshinstudio.com/en/notes/deploy-gotchas/)

Koshin Studio 開発の記録 ／ 2026年10月

  このサイトは、HTML を組み立てて、Cloudflare Pages に配っています。作っていた 9 月の 1 日のうちに、「手元では動くのに、配ると壊れる」という種類の事故が、4 つ続きました。コミットに残っている記録で、順に書きます。

## 1. 直したのに、古いものが動き続けた

  ロゴの弾け方を直したのに、戻ってきた人には、古い動きのままに見える。原因は、style.css と motion.js の名前が変わらないことでした。一度読み込んだブラウザが、1 日、持ち続けていました。配り直しても、手元の画面は新しいので、気づきません。

  直し方は、ファイルの中身から作った印（sha1 の頭 8 桁）を、名前の尻に付けること（style.css?v=19008d13 のような形）です。中身を直せば、別のものとして取りに行きます。書体にも、同じ印を付けました。字を足して作り直したのに、古い書体を掴むと、字が出なくなる（豆腐になる）からです。

  名前が変わるようになったので、保持の期間は、1 日から 30 日に延ばしました。組み直しても印は増えず、中身が同じなら、同じ印になることを、確かめてあります。

## 2. 組み直すたびに、中身が増えていった

  すし積むの作品ページで、パンくずリストが 14 個に増えていました。このサイトの組み立ては、出来上がった HTML を書き換える作りです。差し込みの前に、前回の差し込みを「消す」処理があるのですが、その消す側が一致していないと、組むたびに積み重なります。

- パンくず：消す側の正規表現が class="crumbs" だけを見ていて、aria-label の付いた実物に一致していなかった。

- RSS の link：消す側が、そもそも無く、毎回足されていた。

  同じ形の事故を、機械が見つけるようにしました。本命は、二度組んで、一文字でも変わったページを知らせる検査です。あわせて、帯・脚・本文・パンくず・見出しが二重に出ていないかも見ます。この検査を入れた直後に、RSS のほうが引っかかりました。

## 3. 自分の環境の中を指す symlink を、git に入れていた

  tools/node_modules が、この環境の中を指すシンボリックリンクでした。それを git に入れてしまうと、他の機械では実体が無く、Cloudflare に配るもの（wrangler）を数える所で止まります。実際に止めました。追跡から外し、さらに、追跡されているファイルにシンボリックリンクがあれば、検査で知らせるようにしました。

## 4. 手元だけ、動いていた

  手元には、git に入れていない絵や、前に作ったままの残りがあります。そのせいで、手元だけ動いて、配ると 404 になることがあります。実際に、遊ぶページの favicon がそうでした。

  そこで、コミット済みの中身だけを別の場所へ写し、組み直して、全ページを読み込んでみる検査を足しました。配らないと決めたもの（.assetsignore に並べたもの）も、写しから同じように落として確かめます。そのとき、8 件を落として、12 ページとも欠けなし、でした。

## 分かったこと

> いちばん信用できないのは、自分の手元。

- 名前が変わらないファイルは、直した中身が届かない。名前に、中身の印を付ける。

- 組み直しの事故は、「二度やって、同じか」で見つかる。一度目の結果は、きれいに見える。

- 手元にあるものと、配るものは、別。新しく clone した状態で、確かめる。

  四つとも、自分で気づいたものではなく、検査を足して、はじめて見つかったものです。ページを見て回るだけでは、見えませんでした。

  この記事は、コミット（2026年9月8日）の記録から書きました。

  この話に出てくるもの

- JSONLを読んだら壊れた (https://koshinstudio.com/notes/u2028/) — 「見た目では分からない」食い違いの、別の記録

- 10秒ピッタリのランキングを、公平にする (https://koshinstudio.com/notes/stopwatch-rank/) — 公開した日のつまずきも書いた、別の記録