diff --git a/README.md b/README.md
index 5807c1e..3ce18d1 100755
--- a/README.md
+++ b/README.md
@@ -10,6 +10,38 @@ npm run dev
 npm run build
 ```
 
+## 构建号 `buildId.json`
+
+路径：[`src/config/buildId.json`](src/config/buildId.json)
+
+由 [`scripts/bump-build-id.mjs`](scripts/bump-build-id.mjs) 在 **`npm run build` 前**（`prebuild`）自动生成；`npm run dev` 不会改这个文件。
+
+| 字段 | 说明 |
+|------|------|
+| `buildId` | 11 位构建号：`YYYYMMDD`（8 位）+ 当天第几次构建（3 位，001~999），如 `20260706004` |
+| `generatedAt` | 生成时间（ISO） |
+
+侧栏「更新说明」弹窗底部会显示 `版本 · build 构建号`（见 [`src/layouts/index.vue`](src/layouts/index.vue)）。与 [`src/data/appChangelog.js`](src/data/appChangelog.js) 里的 `APP_VERSION` 无关：版本号手动维护，构建号每次正式 build 自动递增。
+
+### `git pull` 提示本地修改会被覆盖
+
+本地执行过 `npm run build` 后，`buildId.json` 常有未提交改动；若远程也更新了同一文件，`git pull` 会中止并提示：
+
+```text
+Your local changes to the following files would be overwritten by merge:
+  src/config/buildId.json
+Please commit your changes or stash them before you merge.
+```
+
+**一般不需要保留或提交这次本地改动**，丢弃后拉取即可（拉完下次 build 会重新生成）：
+
+```sh
+git restore src/config/buildId.json
+git pull
+```
+
+若确需暂存本地改动：`git stash` → `git pull` → `git stash pop`。
+
 ## 变更记录
 
 - **应用内「更新说明」弹层：** [`src/data/appChangelog.js`](src/data/appChangelog.js)