06-成品-PC客户端Kiosk封闭访问端构建法
一、适用场景
- 需要给「纯 Web 系统」补一个桌面端观感的入口：双击即全屏打开、无地址栏无标签页，像原生应用一样运行，但不发行原生客户端（三端统一 Web 的架构拍板不变）。
- 家庭/内网里有一台常开的服务端（群晖、其它 PC 服务端、本机皆可），需要在另一台电脑（如客厅机、书房机）上做一个只访问不承载的瘦客户端。
- 交付物必须极小（本例 ~80KB）、不含任何服务端代码与业务数据，可随意分发。
不适用：要把服务端一起搬过去的场景（那是 06-成品-Windows双形态安装包构建法 / 06-成品-跨机数据迁移先校验后写入SOP）。
二、操作步骤
-
界定边界：包内只放访问端——若干
.bat+ 一份 README + 一枚图标。明确在脚本头注释里写清「本包不含服务端代码与数据，只改变访问形态」，防止后来者误以为要塞服务端。
锚点：程序源代码/deploy/pc-client/build_pc_client.pyL3-11（模块 docstring）。 -
浏览器探测用「先 set 变量 → 再 dir 引号检测」（本流程最关键的一步）：
bat set "EDGE_X86=%ProgramFiles(x86)%\Microsoft\Edge\Application\msedge.exe" dir "%EDGE_X86%" >nul 2>&1 && if not defined BROWSER set "BROWSER=%EDGE_X86%"
候选顺序 Chrome(x64→x86→LOCALAPPDATA) → Edge(x86→x64) → Chromium。
锚点：pkgroot/start.batL21-35。 -
独立 profile 启动，不污染用户日常浏览器：
bat start "" "%BROWSER%" --kiosk --user-data-dir="%PROFILE%" --no-first-run ^ --no-default-browser-check --disable-infobars --disable-features=Translate "%URL%"
锚点：pkgroot/start.batL86-87（PROFILE定义见 L13）。 -
服务端地址可配置：首次运行若无
client.conf则调set-server.bat询问并落盘；后续从 conf 读URL=（默认http://127.0.0.1:6666）。
锚点：pkgroot/start.batL37-42（读取）、L67-75（首跑询问）。 -
内置
--check自检模式：只报告（浏览器找到与否 / 路径 / 地址 / 配置状态）不启动，方便在出问题的机器上快速取证。
锚点：pkgroot/start.batL45-56。实测cmd //c "start.bat --check"干净输出、exit 0。 -
.bat入包前规范化（_entry_bytes）：UTF-8 源 → GBK(936) 编码 + 全 CRLF + 剔除chcp行，非.bat原样返回。
锚点：build_pc_client.py_entry_bytes()L35-50；调用点 L65。 -
打包：
z.writestr(TOP + "/" + name, _entry_bytes(p))内存直写，图标用z.write从候选路径取第一个命中的；ZipFile(..., strict_timestamps=False)防旧文件 mtime<1980 抛错。
锚点：build_pc_client.pyL53-82（FILES清单 L26-32、TOPL25、strict_timestampsL61）。 -
交付前体检：跑
scripts/bat_kiosk_check.py（默认扫pkgroot，--zip可体检已打好的包）。
三、注意边界
- 不发行原生客户端：这是架构拍板，不是偷懒。用户若要求"做成 exe 客户端"，应先确认是否真要本地承载数据；通常只需把本包的启动方式换成安装向导即可（见关联笔记的双形态包）。
pkgroot/下的.ps1是备选实现，当前不在FILES清单内、不随包发布；体检脚本也只扫FILES五项，不要把.ps1的编码问题误判为包缺陷。- Kiosk 全屏下用户可能不知道怎么退出——必须在启动横幅里写明
退出全屏：Alt+F4 或运行 stop.bat（start.batL81-82）。 - 图标是"锦上添花"：嵌不进 PE 资源不影响
.bat运行；要不要嵌图标看交付形态（.bat包只做包内附带 + 快捷方式用）。
四、反例避雷
- ✗
if exist "%ProgramFiles(x86)%\...\msedge.exe"直接探测 → cmd 在解析期就把字面(x86)当成代码块闭合，报... was unexpected at this time，加引号也没用。
解法：先set赋变量（set引号内括号安全），再用dir "变量路径" >nul 2>&1 && ...（dir的引号参数对括号安全，执行期才展开）。 - ✗
echo 路径：%BROWSER%→%BROWSER%展开后含(x86)，同样崩；必须echo 路径： "%BROWSER%"（显示带引号可接受，安全优先）。 - ✗
.bat用纯 LF 入包 → cmd 解析错乱，报「不是内部或外部命令」。必须 CRLF。 - ✗ 批处理中途
chcp 65001→ cmd 重新解码缓冲区，把已读入的中文行截断成乱码命令，症状与上一条相似但更隐蔽（前几行正常、后面莫名报错）。根治是直接以 GBK 落盘，不换页。 - ✗ 不做
--check自检 → 出问题只能让用户双击看一闪而过的黑窗，无法取证。 - ✗ 把服务端/数据塞进客户端包 → 违反三端统一 Web 的拍板，且造成数据多份拷贝。
五、代码锚点 / 实战战绩
锚点：
- 程序源代码/deploy/pc-client/build_pc_client.py：_entry_bytes() L35-50、FILES L26-32、TOP L25、strict_timestamps=False L61、main() L53-82
- 程序源代码/deploy/pc-client/pkgroot/start.bat：浏览器探测 L21-35、conf 读取 L37-42、--check L45-56、无浏览器报错 L58-65、首跑询问 L67-75、Kiosk 启动 L86-87
- pkgroot/stop.bat / set-server.bat / install-shortcut.bat / README_PC客户端.md
- 产物：程序源代码/deploy/pc-client/hfms-pc-client-20261015-v5.zip（~80KB，纯访问端）
战绩：
- 2026-10-15：修掉 (x86) 括号解析崩（5 个探测点全部改为 dir 引号检测）；补 _entry_bytes 规范化；真实 cmd //c "…--check" 自测输出干净、exit 0。
- 2026-10-16：附包只读体检器首跑两种模式均 PASS（源码态 5 文件 / 已打包态 6 条目），A~F 六类问题零命中。
六、关联笔记
- 与
06-成品-Windows双形态安装包构建法互补：它交付"能跑服务端的安装向导 + 便携版"（GB 级、含数据与迁移工具）；本技能交付"只访问不承载"的 KB 级瘦客户端。两者共用.bat规范化三件套（GBK + CRLF + 去 chcp）。 - 与
04-开发-沙箱环境写文件限制规避法配套：writestr内存直写 +strict_timestamps=False的出处。 - 与
06-成品-群晖SPK打包与格式排查法、06-成品-受限宿主守护进程防回收启动法共同构成"三端一套、形态各异"的交付面。
七、版本记录
- v1.0（2026-10-16）：首版。据 2026-10-15 Kiosk 客户端实战固化，含
(x86)cmd 括号铁律、.bat入包规范化、独立 profile 启动、--check自检，附只读体检器scripts/bat_kiosk_check.py。
