diff --git a/deploy/build-linux.sh b/deploy/build-linux.sh
index 8668e4f..ac1d85c 100755
--- a/deploy/build-linux.sh
+++ b/deploy/build-linux.sh
@@ -105,8 +105,15 @@ cp -a "$ROOT/console/config.json" "$STAGE/config.json"
 cp -a "$ROOT/console/scoreboard.png" "$STAGE/scoreboard.png"
 cp -a "$ROOT/rules" "$STAGE/rules"
 # 说明书之类平铺在包根（extraFiles 的 from: extra, to: .）。
-# 这些 .txt 是 deploy/prepare-extra.mjs 从 docs/ 生成到 console/extra/ 的，本脚本不重新生成，
-# 只负责把它们放进包里；没有就跳过（Linux 包不该因为没有说明书而构建失败）。
+# ⚠️ 这些 .txt 由 deploy/prepare-extra.mjs 从 docs/ 生成，**必须在这里现场重新生成一次**：
+#    只拷现成的，包里就会带上"上一次生成时的旧说明书"——已经踩过一次：
+#    包内「升级说明.txt」停在 dev_0.5.2，而源码已经走到 0.5.11。
+#    生成失败**不阻断**构建（Linux 包不该因为说明书而失败），但打印一行警告，别静默发旧文档。
+if [ -f "$ROOT/deploy/prepare-extra.mjs" ] && command -v node >/dev/null 2>&1; then
+  if ! (cd "$ROOT" && node deploy/prepare-extra.mjs >/dev/null 2>&1); then
+    echo "  ⚠️ 随包说明书重新生成失败（node deploy/prepare-extra.mjs），包里可能仍是旧版" >&2
+  fi
+fi
 if [ -d "$ROOT/console/extra" ]; then
   find "$ROOT/console/extra" -maxdepth 1 -type f ! -name '.gitkeep' -exec cp -a {} "$STAGE/" \;
 fi