南强派配套服务中心

纯静态、单页的配套门户：CH340 驱动下载、图形化编程软件下载、浏览器在线固件烧录。

UI 采用 Apple Glassmorphism（磨砂玻璃）风格；ESP Web Tools 完整源码已离线本地化部署到 vendor 目录，所有英文 UI / 错误 / 日志已逐条汉化。

---

1. 目录结构

esp_web_tool/
├── index.html                                  # 主页面
├── assets/
│   ├── css/style.css                           # Glassmorphism 样式
│   ├── js/
│   │   ├── i18n.js                             # 中文化兜底层（覆盖 vendor 漏网英文）
│   │   └── main.js                             # 兼容性体检 / 探活 / 中文 toast
│   └── vendor/esp-web-tools/                   # ESP Web Tools 离线源码
│       ├── _localize.py                        # 汉化脚本（升级时复用）
│       ├── I18N_MAP.md                         # 汉化对照表
│       └── web/                                # 162 处中文化的 dist
│           ├── install-button.js
│           ├── install-dialog-*.js
│           ├── esp32*.js / esp8266*.js
│           ├── stub_flasher_*.js
│           └── *.orig                          # 原版备份（部署时可剔除）
├── firmware/
│   ├── manifest.json                           # 固件清单
│   └── README.txt
├── downloads/
│   ├── CH340/CH341SER.EXE
│   ├── ESP32/                                  # 放置 bootloader/partitions/firmware 等 .bin
│   └── OpenBlock/EspBlockIDE-Setup.exe
├── oss-cors-config.xml                         # 阿里云 OSS CORS 示例
├── README.md
└── 使用说明.md                                 # 给最终用户看的中文操作手册

2. 本地预览

不能用 file:// 双击打开（浏览器会拒绝 ES module 与 fetch）。请在项目根起静态服务器：

python3 -m http.server 8080
# 浏览器访问 http://localhost:8080/

localhost 同样满足 Web Serial 的 secure context 条件，可以直接联调。

3. 部署到阿里云 OSS

1. OSS 控制台创建 Bucket → 开启静态网站托管，默认首页 index.html。
2. 把整个 esp_web_tool/ 目录上传到 Bucket 根。部署时建议剔除 *.orig 备份：

   find assets/vendor/esp-web-tools -name '*.orig' -delete

3. 用 HTTPS 域名访问页面：
   • OSS 默认域名 https://<bucket>.oss-cn-<region>.aliyuncs.com/ 自带 HTTPS；
   • 自定义域名必须开启 HTTPS（上传 SSL 证书或申请阿里云免费证书）。
4. 因为 vendor 已本地化、与页面同源，不再需要 CORS 配置。oss-cors-config.xml 仅在你把固件文件迁到另一个 Bucket 时才用。

4. 关于 Web Serial 的 "localhost 限制" 真相

协议 / 域名	能否调用 navigator.serial？
http://localhost / http://127.0.0.1	✅
https://任意域名（含 OSS 默认域名）	✅
http://公网域名（明文）	❌ Chrome 强制策略，前端无法绕过
file:// 双击打开	❌

ESP Web Tools 本身没有额外的 "localhost only" 限制，它只受 Web Serial 的 secure context 约束。只要 OSS 用 HTTPS 域名访问，浏览器在线烧录就能跑通。main.js 在加载时会检测 isSecureContext，不满足时直接在固件卡片下方贴出中文警告。

5. 中文化是怎么做的

两层防御：

5.1 源码级替换（主翻译）

assets/vendor/esp-web-tools/_localize.py 用 162 条精确规则改写 vendor 里的英文字符串，覆盖：

• 用户可见的对话框文案 / 按钮文字
• 错误提示（new Error(...) 抛出的内容）
• 进度日志（Wrote N bytes、Compressed N bytes to M、Took T seconds）
• 芯片 features（Embedded Flash 4MB、Single Core、Unknown OUI 等）

严格不动状态枚举（"INSTALL", "PROVISIONED", "DASHBOARD" 等）—— 改了对话框会卡死。完整保留清单见 assets/vendor/esp-web-tools/I18N_MAP.md。

5.2 运行时兜底（覆盖漏网）

assets/js/i18n.js 在 DOM 上挂 MutationObserver，对剩余英文做整段精确替换。这层主要应对：

• 升级 ESP Web Tools 后新增的英文（升级前可能没来得及在 _localize.py 加规则）
• esptool-js stub log 之类的第三方输出

5.3 升级流程

cd assets/vendor/esp-web-tools
python3 _localize.py --restore    # 还原到原版
# 替换 web/ 下的 .js 为新版本
python3 _localize.py --check      # 看哪些规则失效
# 修正 _localize.py 后
python3 _localize.py

6. 实用性 / 稳定性 / 适配性优化清单

main.js 的强化项：

优化	说明
安全上下文体检	区分"非 HTTPS"、"file://"、"无 Web Serial"三种情况，分别给出中文提示
下载链接探活	DOMContentLoaded 后异步 HEAD 检查每个 <a data-asset>，发现 404 把按钮置灰，避免用户点了半天才发现资源缺失
manifest 预校验	在 vendor 报错之前，先 fetch manifest.json 做格式与 part 文件可达性校验
中文 toast	监听 installed / installation-error / installation-aborted 事件统一弹中文 toast
防连点	开始在线更新 按钮点击后 1.2 秒内禁用，避免重复打开对话框
全局错误兜底	unhandledrejection 捕获串口相关错误并 toast，避免静默失败

7. 固件配置

打开 firmware/manifest.json，按你的实际芯片 / 编译产物修改 chipFamily、parts.path、offset：

• path 相对于 manifest.json 的位置。当前默认值 ../downloads/ESP32/... 表示从 firmware/ 跳到 downloads/ESP32/。
• offset 必须与 esptool 的真实烧录地址一致。flasher_args.json / Arduino IDE 编译输出里通常能直接抄。

把 bootloader.bin、partitions.bin、boot_app0.bin、firmware.bin 放到 downloads/ESP32/ 即可。

8. 浏览器兼容性

浏览器	是否支持
Chrome / Edge / Opera 桌面版 89+	✅
Chrome Android	❌（Web Serial 暂不支持）
Safari / Firefox	❌
微信 / QQ / 钉钉内置浏览器	❌

不支持的浏览器会在固件卡片处显示中文提示并把烧录按钮渲染为不可用。

9. 部署前自检

• firmware/manifest.json 中 chipFamily 与 offset 已替换成你的实际值
• downloads/ESP32/*.bin 已上传，HEAD 200
• downloads/CH340/CH341SER.EXE 已就位
• downloads/OpenBlock/EspBlockIDE-Setup.exe 已就位
• OSS Bucket 静态网站托管已开启，默认首页 index.html
• *.orig 备份已剔除
• 桌面 Chrome 实测：点击「开始在线更新」→ 选 COM → 看到「正在连接…」、Wrote N 字节…、「烧录完成！」