From 0997d441af8d8220f80e5c11362e32673387fb64 Mon Sep 17 00:00:00 2001
From: JianFeeeee <jianf@noreply.localhost>
Date: Sat, 12 Sep 2026 08:10:27 +0800
Subject: [PATCH] =?UTF-8?q?docs(build):=20=E5=AE=89=E8=A3=85=E5=8C=85?=
 =?UTF-8?q?=E5=B5=8C=E7=9A=84=E6=98=AF=E5=89=8D=E7=AB=AF=E5=BF=AB=E7=85=A7?=
 =?UTF-8?q?=20=E2=80=94=E2=80=94=20=E5=89=8D=E7=AB=AF=E6=94=B9=E5=8A=A8?=
 =?UTF-8?q?=E5=90=8E=E5=BF=85=E9=A1=BB=E9=87=8D=E6=89=93=EF=BC=8C=E5=B9=B6?=
 =?UTF-8?q?=E7=BB=99=E5=87=BA=E8=87=AA=E6=9F=A5=E5=91=BD=E4=BB=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 client/electron/BUILD.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/client/electron/BUILD.md b/client/electron/BUILD.md
index b32f161..5ba9ff5 100644
--- a/client/electron/BUILD.md
+++ b/client/electron/BUILD.md
@@ -12,6 +12,19 @@ npm run build:win       # NSIS 安装器
 
 产物在 `release/`（已在 `.gitignore` 里，不要提交 —— AppImage 约 122MB、deb 约 100MB）。
 
+> ⚠️ **安装包里嵌的是前端的一份快照**（构建时的 `dist/`）。
+> 因此**任何前端改动（组件、样式、主题、背景）之后都必须重打安装包**，
+> 否则 `release/` 里那份会静默地是旧界面 —— 而它本身不会报错，
+> 只有装上去的人会看到与 Web 不一致的样子。
+>
+> 自查（不需要真正安装）：直接查包内 asar 里的 CSS 有没有你刚加的东西：
+>
+> ```bash
+> node -e "const a=require('@electron/asar');const l=a.listPackage('release/linux-unpacked/resources/app.asar');
+> const c=l.find(p=>/\\/dist\\/assets\\/index-.*\\.css$/.test(p));
+> console.log(c, a.extractFile('release/linux-unpacked/resources/app.asar', c.replace(/^\\//,'')).toString().includes('--bg-scrim'))"
+> ```
+
 ## 本机环境的两个坑
 
 ### 1. `SHASUMS256.txt` 不可达 → 构建会卡 10 分钟后失败