文档：补脚本编码坑（.ps1 需 UTF-8 BOM）

实测：无 BOM 的 UTF-8 .ps1 被 WinPS 5.1 按 GBK 解读，中文变乱码且撞坏引号配对，
报"源文本中包含无法识别的标记"/"字符串缺少终止符"，报错行号无规律易误判为逻辑问题。

新增 §7.1：修法（重存为 UTF8BOM / 前缀 BOM 字节）+ 解析器语法校验命令；
排障表补该条目；三个配套脚本已统一加 BOM 并通过解析校验。

docs/环境与部署/Gitea_Runner部署指南.md

@@ -452,6 +452,51 @@ date +%s   # 对比 last_online
 | `config set log.file ...` 报 `unknown config key` | **v4 的 log 段无 `file` 键** | 用 `log.job.dir` 或输出重定向（§3） |
 | `New-Service` 报 **拒绝访问** | Shell 未提权（`IsAdmin=False`） | 右键 PowerShell → **以管理员身份运行**（§4.5） |
 | `New-Service` 报 `找不到与参数名称"WorkingDirectory"匹配的参数` | WinPS 5.1 的 `New-Service` 无此参数 | 去掉它，靠 `--config` 绝对路径 |
+| **脚本报一堆 `源文本中包含无法识别的标记` / `字符串缺少终止符` / 中文显示成 `鐒跺悗鎵ц`** | 🔴 **`.ps1` 无 BOM，WinPS 5.1 按 GBK 解读 UTF-8** | **给脚本加 UTF-8 BOM**（§11） |
+
+### 7.1 🔴 必读：给含中文的 `.ps1` 加 UTF-8 BOM
+
+**这是本机实测踩过的坑**（2026-10-02）。Windows PowerShell 5.1 对**无 BOM** 的脚本文件
+按**系统 ANSI 代码页**（简中 = **GBK / CP936**）解码：
+
+- UTF-8 的中文字节被当 GBK 解 → 显示成 `鐒跺悗鎵ц` 这类乱码；
+- 更糟的是，**乱码字符会撞坏字符串引号配对**（GBK 双字节的尾字节可能是 `"` 或 `\`）
+  → 解析器报 `源文本中包含无法识别的标记` / `字符串缺少终止符: "` / `缺少右"}"`
+  —— 报错行号看起来毫无规律，**极易误判成逻辑问题**。
+
+**修法**：给文件头加 3 字节 `EF BB BF`（UTF-8 BOM）。与仓库里带 BOM 的源文件
+（`Drivers/BSP/UI/*`、`App/cfg_file.c`）是同一个道理。
+
+```powershell
+# 方法 A：PowerShell 重存为 UTF8BOM
+$c = Get-Content "D:\Docker\act_runner\deploy_runner.ps1" -Raw -Encoding UTF8
+[System.IO.File]::WriteAllText("D:\Docker\act_runner\deploy_runner.ps1", $c, (New-Object System.Text.UTF8Encoding($true)))
+```
+
+```bash
+# 方法 B：直接前缀 BOM 字节（bash/Git Bash）
+cd "/d/Docker/act_runner"
+for f in deploy_runner.ps1 install_service.ps1 check_env.ps1; do
+  printf '\xef\xbb\xbf' > "$f.tmp" && cat "$f" >> "$f.tmp" && mv "$f.tmp" "$f"
+done
+```
+
+**校验**：用 PowerShell 解析器（不执行）确认语法干净：
+
+```powershell
+foreach ($f in @("deploy_runner.ps1","install_service.ps1","check_env.ps1")) {
+    $errs = $null
+    $null = [System.Management.Automation.Language.Parser]::ParseFile(
+        "D:\Docker\act_runner\$f", [ref]$null, [ref]$errs)
+    if ($errs.Count) { "$f : FAIL -> $($errs[0].Message)" } else { "$f : OK" }
+}
+```
+
+> 💡 替代方案：改用 **PowerShell 7+（`pwsh`）**，它默认按 UTF-8 读脚本、无需 BOM。
+> 但本机只有 WinPS 5.1，故加 BOM 最省事。
+>
+> 💡 **纯 ASCII 的脚本不受影响**（`check_env.ps1` 虽含中文注释，但若全英文则无此问题）。
+> 本目录三个脚本现已统一加 BOM。
 
 **看日志**：v4 的 `log` 段**没有 `file` 键**，两种落盘方式：
 
@@ -580,7 +625,7 @@ sc.exe start gitea-runner
 # 5) 回网页确认 runner 为 Idle → 然后（经你同意后）push 代码触发第一次 CI
 ```
 
-**配套脚本**（均在 `D:\Docker\act_runner\`）：
+**配套脚本**（均在 `D:\Docker\act_runner\`，**均已加 UTF-8 BOM**，可直接在 WinPS 5.1 运行）：
 
 | 脚本 | 用途 | 需要管理员 |
 |---|---|---|
@@ -594,5 +639,6 @@ sc.exe start gitea-runner
 
 | 日期 | 变更 |
 |---|---|
+| 2026-10-02 | **修 `.ps1` 编码坑（实测）**：无 BOM 的 UTF-8 脚本被 WinPS 5.1 按 GBK 解读 → 中文乱码（`鐒跺悗鎵ц`）并撞坏引号配对，报 `源文本中包含无法识别的标记`/`字符串缺少终止符`。**新增 §7.1「给含中文的 `.ps1` 加 UTF-8 BOM」**（两种修法 + 解析器校验命令）；排障表补该条目；三个配套脚本已统一加 BOM |
 | 2026-10-02 | **按实测修正为 v4.0.1**：act_runner 已更名 **`gitea-runner`**，发布页迁至 `gitea.com/gitea/runner`。**v4 移除 `daemon install/start/stop/status`**（§4.2 改用 `sc.exe` / `New-Service`）；**v4 `log` 段无 `file` 键**（§3 改用 `log.job.dir`）；补 §1.3 命令集对照、§4.5 提权硬约束（`IsAdmin=False` → `New-Service` 拒绝访问）、§6.1 MySQL 直查核验、排障表 +4 条（`accepts at most 0 arg(s)` / `unknown config key log.file` / `拒绝访问` / `WorkingDirectory` 参数） |
 | 2026-10-02 | 初版：针对**本机 Gitea 原生部署**（`D:\Docker\Gitea\gitea.exe` + Windows 服务 + `127.0.0.1:3001`）定制 Runner 端部署全流程。核心要点：`--instance` 用回环地址、`--labels "windows:host"` 必须精确匹配 `runs-on`、PATH 与服务账号坑、MSVC 路径约束、内网 action 拉取的零依赖改法 |