prebuildの処理順序：生成値を更新してから検証する

2026年6月25日更新 2026年10月19日

この記事で学べること

ビルドは、記事やプログラムから配信用のファイルを作る処理です。このサイトでは、本文量から計算する読了時間が古いまま残り、その検査でビルド前の処理が止まる問題がありました。learning_timeは、この読了時間を保存する記事の設定項目です。

値を一度直せば次も通ると考えていましたが、本文が変わると同じ問題が戻りました。原因は手入力の間違いではなく、値を更新する前に検査していたことです。決めた計算規則や表記へ値をそろえる「正規化」を先に行う必要がありました。

ここでは、このサイトで更新と検証をどう分けたかを振り返ります。個々の記事の値を直す対応と、同じ失敗を繰り返さないための処理順序の変更を区別できます。

このサイトでは、AstroとStarlightで配信用ファイルを作り、Vercelというサービスで公開しています。表面上はこれらのビルド失敗に見えても、実際にはprebuildという、ビルド前に準備や検証を行う段階で止まっている場合がありました。

読了時間の処理には、本文から値を計算して書き戻す--writeと、現在の値が計算結果に合うかを確かめる--checkがあります。検証だけでは古い値は直りません。本文が増えて読了時間が変わった状態で検証だけを実行すると、処理が止まります。

対策は、日常の確認を行うdev:checkと、ビルド前のprebuildの両方で、値の更新 → 更新後の値の検証という順序を保証することでした。決まった規則で直せる差分を先にそろえ、残る問題を検証で知らせます。

ビルド前だけに読了時間を更新すると、内容レビューの途中で本文とは別の機械生成差分が現れます。通常の作成・更新フローでは、学習記事の日本語本文と英訳がそろった時点で読了時間を確定し、文章のレビューと値の調整を分けます。

このプロジェクトには、本文量から読了時間を更新する処理があります。計算方法と保持する情報は次のとおりです。

これは、このサイトの計算規則です。別の基準で読了時間を決めるサイトへ、そのまま適用するものではありません。

作成時に正規化しても、レビュー中の加筆や翻訳の修正で本文量は再び変わります。作成時の処理はレビュー前に差分を確定する通常フロー、dev:checkとprebuildは更新漏れや後続編集のずれを拾う安全網です。

一度設定を直しても、後の変更で正規化が抜けたり、検証が先に移ったりすると再発します。このサイトでは、処理結果に加え、次の条件も自動検査します。

記事を一件直すだけでなく、後の変更でも同じ順序を保つことが再発防止になります。ただし、順序が正しくても、計算規則自体の妥当性や本文の内容までは保証できません。

確認する対象は、次の三つに分かれます。

このプロジェクトでは、npm run buildの実行にユーザーの明示承認が必要です。普段は日常の検証を先に行い、ビルドが必要な段階で別に確認します。手元のビルドが通ったことと、公開先で配信できていることも別の結果として扱います。

読了時間の問題は、古い値を一度直すだけでは再発しました。本文レビュー前に値を確定し、後続の確認でも更新してから検証する順序を保つことで、値の修正と内容のレビューを分けられます。さらに、その順序自体も自動検査の対象にします。

自動更新してよいのは、決まった規則で同じ結果に直せる値です。本文の事実誤りや人の判断が必要な内容まで正規化すると、問題を隠してしまいます。値の更新、内容の確認、配信の成否を区別することが、この設計を使える条件です。