@yufengtadian/freedom-cli 1.12.13 → 1.12.14

package/README.md

@@ -1,9 +1,16 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.13）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.14）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
+**v1.12.14 稳定性 / 兼容性 / 打包链路修复**：
+- **Go 壳层并发安全**：`Dispatch` 修复解锁后读共享 index 的数据竞争（消除 UI 事件丢失 / 偶发 panic）；`App.view` 增加互斥锁，`Emit / Quit / WindowHandle` 可在任意 goroutine 安全调用（后端事件推送不再与 Run 竞态）；
+- **多屏适配**：窗口居中改为按窗口所在监视器工作区（rcWork）居中，副屏 / 负坐标 / 任务栏遮挡下均正确；实现改用纯 syscall，不再依赖 `x/sys/windows` 新版 API（老版本 Go 亦可编译）；
+- **窗口与后端健壮性**：`MinWidth / MinHeight` 任一 >0 即生效；后端进程启动前拦截已关闭状态，杜绝孤儿进程 / 二次 Run；前端自绘三按钮回调全部加 `.catch` 兜底，桥接 reject 不再静默失效；`Unbind` 清理 Go 侧绑定表消除泄漏；
+- **Linux 打包根因修复**：壳下载支持代理（`FREEDOM_SHELL_PROXY / ALL_PROXY / HTTPS_PROXY`），直连 GitHub Releases 被墙超时不再导致 linux 产物打包失败；`--platform` 缺值明确报错、zipDir 跨平台（Windows 用 `tar -a`，Linux/macOS 用 `zip`）、`config get` 校验 key、CLI 改用 `process.exitCode` 不截断管道输出；
+- **兼容性**：ARM Windows 识别并提示 x64 仿真运行；DPI 初始化惰性加载，Win7/8 不再 panic。
+
 **v1.12.13 CLI 界面升级与版本检测**：
 - CLI 交互界面升级为 Claude Code 风格：彩色分组帮助菜单、徽章化命令反馈（✓ / ✗ / ⚠ / ➜）、品牌横幅与版本信息卡；非 TTY（管道 / 重定向）或 `NO_COLOR` 下自动降级为纯文本，脚本调用与 CI 输出不受影响；
 - 新增版本检测：`freedom version` / `freedom update` 实时查询 npm registry 对比最新版本，发现新版本即给出 `npm install -g @yufengtadian/freedom-cli@latest` 升级命令；每次命令执行后静默检测一次（24 小时缓存，离线不打扰、不阻塞），有新版本自动提示升级；
@@ -121,9 +128,9 @@ freedom config set outDir dist  # 恢复默认 dist/
 | 模式 | 说明 |
 | --- | --- |
 | `native` | 保留系统原生标题栏，标题栏图标与 exe 图标一致 |
-| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例）。当前仅 Windows 完整实现；macOS / Linux 由系统窗口管理器托管，回退为原生标题栏且窗口控制动作返回明确错误 |
+| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例）。三平台完整实现：Windows 经 `WM_NCCALCSIZE` / `WM_NCHITTEST` / `WM_GETMINMAXINFO` 原生层处理，macOS / Linux 经 `set_decorated` + 原生窗口控制（GTK `gtk_window_*` / Cocoa `performMiniaturize:` 等），行为一致（v1.12.12 起） |
 
-`frameless` 模式下（Windows），前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例；macOS / Linux 上这些动作会 reject，前端应捕获并提示。
+`frameless` 模式下，前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例；三平台窗口控制动作均已接入原生实现（Windows `WM_NCLBUTTONDOWN`、GTK `gtk_window_begin_move_drag`、Cocoa 原生拖动），拖动标题栏 / 双击最大化 / 右键菜单行为一致。
 
 ## 配置（freedom.config.js）
 

package/bin/freedom.js

@@ -8,8 +8,9 @@ run(process.argv.slice(2)).then(async (code) => {
   if (code === 0 && process.argv[2] !== 'tui') {
     try { await maybeNotifyUpdate(); } catch (e) { /* 检测失败静默 */ }
   }
-  process.exit(code || 0);
+  // 用 exitCode 让 Node 自然刷新 stdout 后退出，避免 process.exit 截断管道输出（历史 bug B28）
+  process.exitCode = code || 0;
 }).catch((err) => {
   console.error('[freedom] 执行失败：', err && err.message ? err.message : err);
-  process.exit(1);
+  process.exitCode = 1;
 });

package/lib/build.js

@@ -308,16 +308,26 @@ ${iconEntry}  <key>CFBundleExecutable</key>
 `;
 }
 
-// 用系统 tar（Windows 为 bsdtar）把目录压成 zip：跨平台可用，无需额外依赖
+// 把目录压成 .zip：跨平台零额外依赖（历史 bug B27）
+// - Windows：系统 tar 为 bsdtar，`-a` 按扩展名自动选 zip 压缩器，可用；
+// - Linux/macOS：GNU tar 的 `-a` 不支持 .zip（仅 gzip/bzip2/xz 等），
+//   改用系统 zip 命令（Linux/macOS 自带或常见，缺失时给出安装提示）。
 function zipDir(zipPath, dir) {
   const parent = path.dirname(dir);
   const base = path.basename(dir);
   if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
-  const res = spawnSync('tar', ['-a', '-c', '-f', zipPath, base], { cwd: parent, encoding: 'utf8' });
+  let res;
+  if (process.platform === 'win32') {
+    res = spawnSync('tar', ['-a', '-c', '-f', zipPath, base], { cwd: parent, encoding: 'utf8' });
+  } else {
+    res = spawnSync('zip', ['-r', '-q', zipPath, base], { cwd: parent, encoding: 'utf8' });
+  }
   if (res.error || res.status !== 0) {
-    throw new Error(
-      `打包 ${base} 为 zip 失败：${(res.stderr || res.stdout || '').trim() || res.error.message}`
-    );
+    const detail = (res.stderr || res.stdout || '').trim() || res.error.message;
+    const hint = process.platform !== 'win32'
+      ? '\n（Linux/macOS 打包 zip 需要 zip 命令：Ubuntu: sudo apt install zip / macOS: brew install zip）'
+      : '';
+    throw new Error(`打包 ${base} 为 zip 失败：${detail}${hint}`);
   }
 }
 

package/lib/cli.js

@@ -117,7 +117,17 @@ async function run(argv) {
       const platArg = rest.find((a) => a.startsWith('--platform') || a.startsWith('-p'));
       let platform;
       if (platArg) {
-        platform = platArg.includes('=') ? platArg.split('=')[1] : rest[rest.indexOf(platArg) + 1];
+        const inline = platArg.includes('=') ? platArg.split('=')[1] : undefined;
+        if (inline) {
+          platform = inline;
+        } else {
+          platform = rest[rest.indexOf(platArg) + 1];
+        }
+        // 缺值（--platform 后无值 / 紧跟着另一个选项）时明确报错，禁止静默回退当前平台（历史 bug B26）
+        if (!platform || platform.startsWith('--')) {
+          console.error(`${err('--platform 缺少取值。')} ${dim('用法：')}${paint('freedom build --platform <win|mac|linux|all>', C.fg.cyan)}`);
+          return 1;
+        }
       }
       const { results } = await build(process.cwd(), { platform, noCache: rest.includes('--no-cache') });
       for (const r of results) {
@@ -161,8 +171,18 @@ async function run(argv) {
     case 'config': {
       const sub = rest[0];
       if (sub === 'get') {
-        const cfg = await showConfig(process.cwd());
-        console.log(cfg);
+        const key = rest[1];
+        if (!key) {
+          console.error(`${err('用法：')}${paint('freedom config get <key>', C.fg.cyan)}`);
+          return 1;
+        }
+        const { getConfig } = require('./config');
+        const cfg = await getConfig(process.cwd());
+        if (!(key in cfg)) {
+          console.error(`${err(`配置项 ${key} 不存在。可用键：`)}${paint(Object.keys(cfg).join(' / '), C.fg.cyan)}`);
+          return 1;
+        }
+        console.log(JSON.stringify(cfg[key], null, 2));
         return 0;
       }
       if (sub === 'set') {

package/lib/shell.js

@@ -163,6 +163,55 @@ function hasShell(plat) {
   return fs.existsSync(localShellPath(plat));
 }
 
+// ---- 代理支持（修复：本地无 linux/mac 壳时自动下载必失败的历史根因） ----
+// 背景：GitHub Releases 资产重定向到 S3，Node 内置 fetch 直连在受限网络下
+// body 下载会卡死（可拿到 200 响应头但 arrayBuffer 永远不结束）。本机若跑
+// 在代理后（如 socks5://127.0.0.1:10808），必须显式走代理才能拉取壳资产。
+// 方案：优先识别代理环境变量，存在时改用系统 curl（跨平台自带，原生支持
+// socks5h/http/https 代理）下载，Windows 加 --ssl-no-revoke 规避 schannel
+// 证书吊销离线检查。
+
+// 解析下载代理：专属变量 > 通用标准变量（大小写各试一次）
+function resolveProxy() {
+  const keys = ['FREEDOM_SHELL_PROXY', 'ALL_PROXY', 'all_proxy', 'HTTPS_PROXY', 'https_proxy'];
+  for (const k of keys) {
+    const v = process.env[k];
+    if (v && typeof v === 'string' && v.trim()) return v.trim();
+  }
+  return null;
+}
+
+// curl 是否可用（Windows 10+ 自带 curl.exe；Linux/macOS 系统自带）
+function hasCurl() {
+  if (process.env.FREEDOM_NO_CURL === '1') return false;
+  try {
+    const r = spawnSync('curl', ['--version'], { encoding: 'utf8', windowsHide: true });
+    return !r.error && r.status === 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+// 用 curl 下载到 dest；成功返回 null，失败返回错误信息
+function curlDownload(url, dest, proxy) {
+  const args = [
+    '-L', '--fail', '--silent', '--show-error',
+    '--connect-timeout', '20', '--max-time', '180', '--retry', '2',
+    '--output', dest,
+  ];
+  if (proxy) args.push('--proxy', proxy);
+  if (process.platform === 'win32' && /^https:/i.test(url)) {
+    args.push('--ssl-no-revoke'); // 规避 Windows schannel CRYPT_E_REVOCATION_OFFLINE
+  }
+  args.push(url);
+  const r = spawnSync('curl', args, { encoding: 'utf8', windowsHide: true, maxBuffer: 8 * 1024 * 1024 });
+  if (r.error || r.status !== 0) {
+    const detail = (r.stderr || r.stdout || '').trim() || (r.error && r.error.message) || '未知错误';
+    return `curl 下载失败（exit=${r.status}）：${detail}`;
+  }
+  return null;
+}
+
 // 下载指定平台壳到包内 shell/<plat>/
 // 返回下载后的绝对路径；失败抛错。
 async function downloadShell(plat) {
@@ -173,24 +222,59 @@ async function downloadShell(plat) {
   const dest = localShellPath(plat);
   fs.mkdirSync(path.dirname(dest), { recursive: true });
 
-  process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
-  let res;
-  try {
-    // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
-    res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
-  } catch (e) {
-    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
-      throw new Error(`下载壳 ${plat} 超时（30s）。请检查网络后重试，或手动将壳二进制放入 ${localShellPath(plat)}。`);
+  const proxy = resolveProxy();
+  let buf;
+  if (proxy) {
+    process.stdout.write(`[freedom] 下载壳 ${plat}（经代理 ${proxy}）<- ${url}\n`);
+    if (!hasCurl()) {
+      throw new Error(
+        `已配置下载代理 ${proxy} 但本机没有 curl，无法经代理下载壳。` +
+          `请安装 curl，或临时取消代理变量后直连重试。`
+      );
     }
-    throw new Error(`下载壳 ${plat} 失败：${e.message}。请检查网络，或手动将壳二进制放入 ${localShellPath(plat)}。`);
-  }
-  if (!res.ok) {
-    throw new Error(
-      `下载壳失败：HTTP ${res.status}。请确认 GitHub 仓库 ${releaseRepo()} 已发布 ` +
-        `${releaseTag()} 的资产 freedom-shell-${plat}，或手动将壳二进制放入 ${localShellPath(plat)}。`
-    );
+    const tmp = `${dest}.tmp`;
+    const curlErr = curlDownload(url, tmp, proxy);
+    if (curlErr) {
+      try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
+      throw new Error(
+        `${curlErr}\n下载地址 ${url} 不可达。` +
+          `请确认代理 ${proxy} 可用（可执行 curl --proxy ${proxy} ${url} -I 自测），` +
+          `或手动将壳二进制放入 ${localShellPath(plat)}。`
+      );
+    }
+    try {
+      buf = fs.readFileSync(tmp);
+    } finally {
+      try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
+    }
+  } else {
+    process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
+    let res;
+    try {
+      // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
+      res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
+    } catch (e) {
+      if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+        throw new Error(
+          `下载壳 ${plat} 超时（30s）。请检查网络后重试，` +
+            `或设置代理变量 FREEDOM_SHELL_PROXY=socks5h://127.0.0.1:10808 重试，` +
+            `或手动将壳二进制放入 ${localShellPath(plat)}。`
+        );
+      }
+      throw new Error(
+        `下载壳 ${plat} 失败：${e.message}。请检查网络（必要时设置 FREEDOM_SHELL_PROXY 走代理），` +
+          `或手动将壳二进制放入 ${localShellPath(plat)}。`
+      );
+    }
+    if (!res.ok) {
+      throw new Error(
+        `下载壳失败：HTTP ${res.status}。请确认 GitHub 仓库 ${releaseRepo()} 已发布 ` +
+          `${releaseTag()} 的资产 freedom-shell-${plat}，或手动将壳二进制放入 ${localShellPath(plat)}。`
+      );
+    }
+    buf = Buffer.from(await res.arrayBuffer());
   }
-  const buf = Buffer.from(await res.arrayBuffer());
+
   // B13：下载后、落盘前校验格式/架构，防止代理劫持返回错误页或假壳被静默分发。
   const fmt = detectShellFormat(buf);
   const want = expectedFormat(plat);

package/lib/tui.js

@@ -254,7 +254,13 @@ async function configFlow(tui, cwd) {
     const [key, desc] = CONFIG_KEYS[idx - 1];
     const val = await tui.input(`${key}`, { initial: '' });
     if (val === null) continue;
-    setConfig(cwd, key, coerce(val));
+    try {
+      setConfig(cwd, key, coerce(val));
+    } catch (e) {
+      // 抛错必须留在 TUI 内提示，否则绕过 exit() 导致终端残留 raw mode / 光标隐藏（历史 bug B12）
+      await tui.message('配置', [{ text: C.fgRed + `  设置失败：${e.message}` + C.reset }]);
+      continue;
+    }
     await tui.message('配置', [{ text: C.fgGreen + `  ${key} = ${val}` + C.reset }]);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.12.13",
+  "version": "1.12.14",
   "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
   "keywords": [
     "desktop",

package/templates/go/main.go

@@ -4,7 +4,8 @@ import "freedom-cli-shell/pkg/freedom"
 
 // main 是 Freedom 壳层应用入口。
 // 窗口与标题栏配置来自 build 阶段生成的 gen_config.go（appConfig），
-// 前端页面由 pkg/freedom 的 assets_embed.go 嵌入（build 阶段把打包后的 index.html 放进去）。
+// 前端页面运行时从 exe 同目录 resources/index.html 加载（build 阶段由 CLI
+// 把打包后的 index.html 与 config.json 写入该目录，壳 SetHtml 内存加载、不占端口）。
 func main() {
 	cfg := appConfig()
 	app := freedom.New(cfg)

package/templates/go/pkg/freedom/assets/freedom.js

@@ -71,13 +71,19 @@
     var q = function (s) { return typeof s === 'string' ? document.querySelector(s) : s; };
     var min = q(sel && sel.min), max = q(sel && sel.max), close = q(sel && sel.close);
     var self = this;
-    if (min) min.addEventListener('click', function () { self.minimize(); });
+    // 所有桥接调用均带 .catch：页面先于桥接就绪时点击按钮会产生未捕获的
+    // Promise rejection（并导致自绘标题栏静默失效），此处兜底为控制台告警。
+    if (min) min.addEventListener('click', function () {
+      self.minimize().catch(function (e) { console.warn('[freedom] minimize:', e); });
+    });
     if (max) max.addEventListener('click', function () {
       self.isMaximized().then(function (m) {
-        if (m) self.unmaximize(); else self.maximize();
-      });
+        if (m) return self.unmaximize(); else return self.maximize();
+      }).catch(function (e) { console.warn('[freedom] maximize toggle:', e); });
+    });
+    if (close) close.addEventListener('click', function () {
+      self.close().catch(function (e) { console.warn('[freedom] close:', e); });
     });
-    if (close) close.addEventListener('click', function () { self.close(); });
   };
 
   function windowAction(action) {

package/templates/go/pkg/freedom/backend_proc.go

@@ -97,6 +97,9 @@ func (p *ProcBackend) OnEvent(fn func(event string, data interface{})) {
 func (p *ProcBackend) start() error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
+	if p.closed {
+		return fmt.Errorf("freedom: proc backend is closed")
+	}
 	if p.stdin != nil {
 		return nil // 已启动
 	}

package/templates/go/pkg/freedom/center_windows.go

@@ -8,18 +8,36 @@ import (
 )
 
 var (
-	user32           = syscall.NewLazyDLL("user32.dll")
-	getSystemMetrics = user32.NewProc("GetSystemMetrics")
-	moveWindow       = user32.NewProc("MoveWindow")
+	user32            = syscall.NewLazyDLL("user32.dll")
+	getSystemMetrics  = user32.NewProc("GetSystemMetrics")
+	moveWindow        = user32.NewProc("MoveWindow")
+	monitorFromWindow = user32.NewProc("MonitorFromWindow")
+	getMonitorInfo    = user32.NewProc("GetMonitorInfoW")
 )
 
 const (
-	smCxScreen = 16
-	smCyScreen = 17
+	smCxScreen           = 16
+	smCyScreen           = 17
+	monitorDefaultToNear = 2 // MONITOR_DEFAULTTONEAREST
 )
 
+type rect struct {
+	left, top, right, bottom int32
+}
+
+// monitorInfo 对应 Win32 MONITORINFO（cbSize 置 0 时用 struct 大小填充，
+// 32 位下与 64 位下布局一致，字段对齐与 cbSize 校验兼容）。
+type monitorInfo struct {
+	cbSize    uint32
+	rcMonitor rect
+	rcWork    rect
+	dwFlags   uint32
+}
+
 // applyCenter 在 Windows 上把窗口置于屏幕中央（需在 SetSize 之后调用）。
 // webview_go 未提供 SetPosition，这里通过原生 HWND + MoveWindow 定位。
+// 优先居中到窗口当前所在监视器的工作区（rcWork）：多屏副屏（负坐标 /
+// 不同分辨率 / 任务栏遮挡）下也能正确居中；API 失败时回退主屏全屏居中。
 func (a *App) applyCenter() {
 	if !a.cfg.Center || a.view == nil {
 		return
@@ -28,6 +46,27 @@ func (a *App) applyCenter() {
 	if hwnd == 0 {
 		return
 	}
+	mon, _, _ := monitorFromWindow.Call(hwnd, monitorDefaultToNear)
+	if mon != 0 {
+		var mi monitorInfo
+		mi.cbSize = uint32(unsafe.Sizeof(mi))
+		if r1, _, _ := getMonitorInfo.Call(mon, uintptr(unsafe.Pointer(&mi))); r1 != 0 {
+			work := mi.rcWork
+			sw := work.right - work.left
+			sh := work.bottom - work.top
+			x := work.left + (sw-int32(a.cfg.Width))/2
+			y := work.top + (sh-int32(a.cfg.Height))/2
+			if x < 0 {
+				x = 0
+			}
+			if y < 0 {
+				y = 0
+			}
+			moveWindow.Call(hwnd, uintptr(x), uintptr(y), uintptr(a.cfg.Width), uintptr(a.cfg.Height), 1)
+			return
+		}
+	}
+	// 回退：主屏全屏尺寸居中（原实现）
 	sw, _, _ := getSystemMetrics.Call(smCxScreen)
 	sh, _, _ := getSystemMetrics.Call(smCyScreen)
 	x := int(sw/2) - a.cfg.Width/2

package/templates/go/pkg/freedom/freedom.go

@@ -1,283 +1,303 @@
-// Package freedom 是一个从零自研的 WebView 桌面壳子框架（对标 Wails / Tauri）。
-//
-// Freedom 2.0 架构：
-//   - shell：跨平台渲染壳。复用各系统自带 WebView 内核（Windows WebView2 / macOS
-//     WKWebView / Linux WebKitGTK），通过跨平台库 webview_go 绑定，自身不携带浏览器
-//     内核。壳负责窗口生命周期、前端资源 embed、后端进程管理、IPC 路由。一份壳代码
-//     编译三平台。
-//   - backend：后端抽象。任意时刻绑定一个后端，前端 window.freedom.call 全部路由过去。
-//     内置两种实现：
-//       * EmbedBackend：Go 方法直接注册在壳进程内（app.Bind，兼容 v1 用法）。
-//       * ProcBackend：后端是任意语言实现的独立进程（Go/Rust/Python/Node/Java…），
-//         通过 stdin/stdout 上的 NDJSON/JSON-RPC 与壳通信。协议语言无关，
-//         换一种后端语言无需改壳与前端。
-//   - ipc：双向桥接。前端 window.freedom.call(method, ...args) -> Promise；
-//     后端 app.Emit(event, data) 向所有前端监听器推送事件。
-//   - assets：前端编译产物（Vite 单文件 HTML）通过 go:embed 嵌入二进制，运行时
-//     直接 SetHtml 从内存加载，无需本地 HTTP 端口。
-package freedom
-
-import (
-	"encoding/json"
-	"fmt"
-	"unsafe"
-
-	webview "github.com/webview/webview_go"
-)
-
-// TitleBarMode 描述窗口标题栏策略。
-type TitleBarMode string
-
-const (
-	// TitleBarNative 保留系统原生标题栏（默认），标题栏图标与 exe 图标一致。
-	TitleBarNative TitleBarMode = "native"
-	// TitleBarFrameless 完全无边框，客户区铺满整个窗口。
-	// 标题栏与系统原生最小化 / 最大化 / 关闭按钮均不存在，
-	// 需由前端自绘（通过 window.freedom.window.* 控制），三平台行为一致。
-	TitleBarFrameless TitleBarMode = "frameless"
-)
-
-// Config 描述一个 Freedom 应用的窗口与运行配置。
-type Config struct {
-	// Title 是窗口标题。
-	Title string
-	// TitleBar 指定标题栏策略（默认 TitleBarNative）。可通过 freedom CLI 一键切换。
-	TitleBar TitleBarMode
-	// Width / Height 是窗口初始尺寸（像素）。
-	Width  int
-	Height int
-	// Center 为 true 时窗口在屏幕居中（Windows 生效；macOS/Linux 由窗口管理器决定）。
-	Center bool
-	// MinWidth / MinHeight 为窗口最小尺寸（<=0 表示不限制）。
-	MinWidth  int
-	MinHeight int
-	// Debug 为 true 时开启 WebView 开发者工具（目标平台支持时）。
-	Debug bool
-	// Backend 指定后端适配器。为空时默认使用内嵌 Go 后端（配合 Bind 使用）。
-	Backend Backend
-	// HTML 返回要加载到窗口的前端页面内容（内存加载，无本地端口）。
-	// 为 nil 时使用框架内置的默认占位页。
-	HTML func() (string, error)
-}
-
-// App 是 Freedom 应用实例。
-type App struct {
-	cfg             Config
-	view            webview.WebView
-	backend         Backend
-	backendExplicit bool // 调用方是否显式指定了后端（外部 config.json 不应覆盖显式绑定）
-	onReady         func(a *App)
-}
-
-// New 创建并初始化一个 Freedom 应用。调用 Run() 之前不会显示窗口。
-func New(cfg Config) *App {
-	if cfg.Title == "" {
-		cfg.Title = "Freedom App"
-	}
-	if cfg.TitleBar == "" {
-		cfg.TitleBar = TitleBarNative
-	}
-	if cfg.Width <= 0 {
-		cfg.Width = 1024
-	}
-	if cfg.Height <= 0 {
-		cfg.Height = 768
-	}
-	explicit := cfg.Backend != nil
-	if !explicit {
-		cfg.Backend = NewEmbedBackend()
-	}
-	return &App{cfg: cfg, backend: cfg.Backend, backendExplicit: explicit}
-}
-
-// OnReady 注册一个回调，在窗口与桥接层就绪、页面加载前执行。
-// 回调内可以安全调用 Emit 向已注入的页面发送初始化事件。
-func (a *App) OnReady(fn func(a *App)) {
-	a.onReady = fn
-}
-
-// Bind 把后端 Go 方法暴露给前端。仅当后端为内嵌 Go 后端（默认）时有效；
-// 进程后端的方法由后端进程自身注册，此处调用会返回错误。
-//
-//   - fn 必须是函数。
-//   - 参数与返回值通过 JSON 编解码，前端用 window.freedom.call(name, ...args) 调用，
-//     返回 Promise（resolve 为返回值，reject 为 error 的字符串表示）。
-//   - 返回值约定：可返回 (T, error) 或仅 (T) 或仅 error 或空。
-func (a *App) Bind(name string, fn interface{}) error {
-	eb, ok := a.backend.(*EmbedBackend)
-	if !ok {
-		return fmt.Errorf("freedom: Bind 仅适用于内嵌 Go 后端；当前后端为 %T，方法请在进程后端中注册", a.backend)
-	}
-	return eb.Bind(name, fn)
-}
-
-// Unbind 移除先前 Bind 的方法（内嵌后端）。
-func (a *App) Unbind(name string) {
-	if eb, ok := a.backend.(*EmbedBackend); ok {
-		eb.Unbind(name)
-	}
-}
-
-// Run 启动窗口并进入主事件循环，阻塞直到窗口被关闭。
-func (a *App) Run() {
-	// 通用壳：先加载 exe 同目录 resources/config.json 覆盖窗口与后端配置
-	//（CLI build 时写入；缺失则使用编译期/默认配置）。
-	// 配置存在但非法时打印告警（不中断启动），避免用户手改配置出错时静默无感。
-	if err := a.loadRuntimeConfig(); err != nil {
-		fmt.Printf("freedom: warning: %v\n", err)
-	}
-
-	html, err := a.resolveHTML()
-	if err != nil {
-		fmt.Printf("freedom: failed to resolve HTML: %v\n", err)
-		return
-	}
-
-	w := webview.New(a.cfg.Debug)
-	if w == nil {
-		fmt.Println("freedom: failed to create webview")
-		return
-	}
-	a.view = w
-	defer func() {
-		_ = a.backend.Close()
-		w.Destroy()
-	}()
-
-	// 进程后端：启动后端进程并把其推送的事件转发到前端。
-	if pb, ok := a.backend.(*ProcBackend); ok {
-		pb.OnEvent(func(event string, data interface{}) {
-			a.Emit(event, data)
-		})
-		if err := pb.start(); err != nil {
-			fmt.Printf("freedom: backend start failed: %v\n", err)
-			return
-		}
-	}
-
-	w.SetTitle(a.cfg.Title)
-	w.SetSize(a.cfg.Width, a.cfg.Height, webview.HintNone)
-	if a.cfg.MinWidth > 0 && a.cfg.MinHeight > 0 {
-		w.SetSize(a.cfg.MinWidth, a.cfg.MinHeight, webview.HintMin)
-	}
-	a.applyCenter()
-	a.applyTitleBar()
-	a.setWindowIcon()
-
-	// 注入前端 SDK：window.freedom 全局对象。
-	w.Init(jsSDK)
-
-	// 绑定 IPC 桥接入口：前端 window.__freedom_bridge(method, paramsJson)。
-	// webview_go 的 Bind 会让前端调用返回 Promise，Go 侧结果自动 JSON 序列化回传。
-	if err := w.Bind("__freedom_bridge", a.bridge); err != nil {
-		fmt.Printf("freedom: failed to bind bridge: %v\n", err)
-		return
-	}
-	// 框架内置方法：健康检查。
-	if err := w.Bind("__freedom__ping", func() string { return "pong" }); err != nil {
-		fmt.Printf("freedom: failed to bind ping: %v\n", err)
-		return
-	}
-	// 框架内置方法：窗口控制（无边框模式下前端自绘按钮使用）。
-	// 支持动作：minimize / maximize / unmaximize / toggleMaximize / close / isMaximized / isFrameless。
-	if err := w.Bind("__freedom_window", a.windowControl); err != nil {
-		fmt.Printf("freedom: failed to bind window control: %v\n", err)
-		return
-	}
-
-	if a.onReady != nil {
-		a.onReady(a)
-	}
-
-	w.SetHtml(html)
-	w.Run()
-}
-
-// bridge 是前端调用后端的统一入口（JSON-RPC 风格）。
-// 前端 SDK 通过 window.__freedom_bridge(method, paramsJson) 调用，
-// 桥接层把请求转发给当前绑定的后端（内嵌 Go 方法或任意语言进程）。
-func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage, err error) {
-	// 防御后端方法 panic 导致整个窗口崩溃：统一转为错误回传前端。
-	defer func() {
-		if r := recover(); r != nil {
-			result = nil
-			err = fmt.Errorf("freedom: method %q panicked: %v", method, r)
-		}
-	}()
-
-	var params []json.RawMessage
-	if len(paramsJSON) > 0 && paramsJSON != "null" {
-		if err := json.Unmarshal([]byte(paramsJSON), &params); err != nil {
-			return nil, fmt.Errorf("freedom: method %q: invalid params: %w", method, err)
-		}
-	}
-
-	// 框架内置方法特判：__freedom__ping 由 webview Bind 注册为全局函数
-	// window.__freedom__ping()，同时兼容经 freedom.call()/__freedom_bridge 路由的旧写法，
-	// 避免模板"测试桥接"自检报"method not bound"。
-	if method == "__freedom__ping" {
-		return json.RawMessage(`"pong"`), nil
-	}
-
-	raw, err := a.backend.Handle(method, params)
-	if err != nil {
-		return nil, err
-	}
-	data, err := json.Marshal(raw)
-	if err != nil {
-		return nil, fmt.Errorf("freedom: method %q: cannot marshal result: %w", method, err)
-	}
-	return json.RawMessage(data), nil
-}
-
-// Emit 把事件推送到前端。前端通过 window.freedom.on(event, cb) 订阅。
-// 线程安全：可从任意 goroutine 调用（进程后端推送的事件亦经由本函数）。
-func (a *App) Emit(event string, data interface{}) {
-	if a.view == nil {
-		return
-	}
-	eb, _ := json.Marshal(event)
-	db, err := json.Marshal(data)
-	if err != nil {
-		db = []byte("null")
-	}
-	js := "window.freedom && window.freedom.emit(" + string(eb) + "," + string(db) + ");"
-	a.view.Dispatch(func() {
-		a.view.Eval(js)
-	})
-}
-
-// Quit 关闭窗口并退出应用。可从任意 goroutine 调用。
-func (a *App) Quit() {
-	if a.view != nil {
-		a.view.Dispatch(func() {
-			a.view.Terminate()
-		})
-	}
-}
-
-// WindowHandle 返回底层原生窗口句柄（Windows 上为 HWND）。
-func (a *App) WindowHandle() uintptr {
-	if a.view == nil {
-		return 0
-	}
-	return uintptr(unsafe.Pointer(a.view.Window()))
-}
-
-// windowControl 处理前端 window.freedom.window.* 的窗口控制请求。
-// 具体实现按平台分文件：window_windows.go（Windows）/ window_other.go（macOS、Linux）。
-func (a *App) windowControl(action string) (interface{}, error) {
-	return windowControl(a, action)
-}
-
-// resolveHTML 依据配置返回页面内容。
-// 优先级：exe 同目录 resources/index.html（预编译通用壳，CLI build 写入）> cfg.HTML > 内置占位页。
-func (a *App) resolveHTML() (string, error) {
-	if html, err := loadRuntimeHTML(); err == nil && html != "" {
-		return html, nil
-	}
-	if a.cfg.HTML != nil {
-		return a.cfg.HTML()
-	}
-	return defaultHTML, nil
-}
+// Package freedom 是一个从零自研的 WebView 桌面壳子框架（对标 Wails / Tauri）。
+//
+// Freedom 2.0 架构：
+//   - shell：跨平台渲染壳。复用各系统自带 WebView 内核（Windows WebView2 / macOS
+//     WKWebView / Linux WebKitGTK），通过跨平台库 webview_go 绑定，自身不携带浏览器
+//     内核。壳负责窗口生命周期、前端资源 embed、后端进程管理、IPC 路由。一份壳代码
+//     编译三平台。
+//   - backend：后端抽象。任意时刻绑定一个后端，前端 window.freedom.call 全部路由过去。
+//     内置两种实现：
+//       * EmbedBackend：Go 方法直接注册在壳进程内（app.Bind，兼容 v1 用法）。
+//       * ProcBackend：后端是任意语言实现的独立进程（Go/Rust/Python/Node/Java…），
+//         通过 stdin/stdout 上的 NDJSON/JSON-RPC 与壳通信。协议语言无关，
+//         换一种后端语言无需改壳与前端。
+//   - ipc：双向桥接。前端 window.freedom.call(method, ...args) -> Promise；
+//     后端 app.Emit(event, data) 向所有前端监听器推送事件。
+//   - assets：前端编译产物（Vite 单文件 HTML）通过 go:embed 嵌入二进制，运行时
+//     直接 SetHtml 从内存加载，无需本地 HTTP 端口。
+package freedom
+
+import (
+	"encoding/json"
+	"fmt"
+	"sync"
+	"unsafe"
+
+	webview "github.com/webview/webview_go"
+)
+
+// TitleBarMode 描述窗口标题栏策略。
+type TitleBarMode string
+
+const (
+	// TitleBarNative 保留系统原生标题栏（默认），标题栏图标与 exe 图标一致。
+	TitleBarNative TitleBarMode = "native"
+	// TitleBarFrameless 完全无边框，客户区铺满整个窗口。
+	// 标题栏与系统原生最小化 / 最大化 / 关闭按钮均不存在，
+	// 需由前端自绘（通过 window.freedom.window.* 控制），三平台行为一致。
+	TitleBarFrameless TitleBarMode = "frameless"
+)
+
+// Config 描述一个 Freedom 应用的窗口与运行配置。
+type Config struct {
+	// Title 是窗口标题。
+	Title string
+	// TitleBar 指定标题栏策略（默认 TitleBarNative）。可通过 freedom CLI 一键切换。
+	TitleBar TitleBarMode
+	// Width / Height 是窗口初始尺寸（像素）。
+	Width  int
+	Height int
+	// Center 为 true 时窗口在屏幕居中（Windows 生效；macOS/Linux 由窗口管理器决定）。
+	Center bool
+	// MinWidth / MinHeight 为窗口最小尺寸（<=0 表示不限制）。
+	MinWidth  int
+	MinHeight int
+	// Debug 为 true 时开启 WebView 开发者工具（目标平台支持时）。
+	Debug bool
+	// Backend 指定后端适配器。为空时默认使用内嵌 Go 后端（配合 Bind 使用）。
+	Backend Backend
+	// HTML 返回要加载到窗口的前端页面内容（内存加载，无本地端口）。
+	// 为 nil 时使用框架内置的默认占位页。
+	HTML func() (string, error)
+}
+
+// App 是 Freedom 应用实例。
+type App struct {
+	cfg             Config
+	viewMu          sync.Mutex // 保护 view 字段（Run 写 / Emit·Quit·WindowHandle 任意 goroutine 读）
+	view            webview.WebView
+	backend         Backend
+	backendExplicit bool // 调用方是否显式指定了后端（外部 config.json 不应覆盖显式绑定）
+	onReady         func(a *App)
+}
+
+// New 创建并初始化一个 Freedom 应用。调用 Run() 之前不会显示窗口。
+func New(cfg Config) *App {
+	if cfg.Title == "" {
+		cfg.Title = "Freedom App"
+	}
+	if cfg.TitleBar == "" {
+		cfg.TitleBar = TitleBarNative
+	}
+	if cfg.Width <= 0 {
+		cfg.Width = 1024
+	}
+	if cfg.Height <= 0 {
+		cfg.Height = 768
+	}
+	explicit := cfg.Backend != nil
+	if !explicit {
+		cfg.Backend = NewEmbedBackend()
+	}
+	return &App{cfg: cfg, backend: cfg.Backend, backendExplicit: explicit}
+}
+
+// OnReady 注册一个回调，在窗口与桥接层就绪、页面加载前执行。
+// 回调内可以安全调用 Emit 向已注入的页面发送初始化事件。
+func (a *App) OnReady(fn func(a *App)) {
+	a.onReady = fn
+}
+
+// Bind 把后端 Go 方法暴露给前端。仅当后端为内嵌 Go 后端（默认）时有效；
+// 进程后端的方法由后端进程自身注册，此处调用会返回错误。
+//
+//   - fn 必须是函数。
+//   - 参数与返回值通过 JSON 编解码，前端用 window.freedom.call(name, ...args) 调用，
+//     返回 Promise（resolve 为返回值，reject 为 error 的字符串表示）。
+//   - 返回值约定：可返回 (T, error) 或仅 (T) 或仅 error 或空。
+func (a *App) Bind(name string, fn interface{}) error {
+	eb, ok := a.backend.(*EmbedBackend)
+	if !ok {
+		return fmt.Errorf("freedom: Bind 仅适用于内嵌 Go 后端；当前后端为 %T，方法请在进程后端中注册", a.backend)
+	}
+	return eb.Bind(name, fn)
+}
+
+// Unbind 移除先前 Bind 的方法（内嵌后端）。
+func (a *App) Unbind(name string) {
+	if eb, ok := a.backend.(*EmbedBackend); ok {
+		eb.Unbind(name)
+	}
+}
+
+// getView / setView 以互斥锁保护 view 字段：Run 在主 goroutine 写，
+// Emit/Quit/WindowHandle 可能被任意 goroutine（如后端事件推送）读，
+// 无保护时 race detector 报数据竞争。
+func (a *App) getView() webview.WebView {
+	a.viewMu.Lock()
+	defer a.viewMu.Unlock()
+	return a.view
+}
+
+func (a *App) setView(v webview.WebView) {
+	a.viewMu.Lock()
+	a.view = v
+	a.viewMu.Unlock()
+}
+
+// Run 启动窗口并进入主事件循环，阻塞直到窗口被关闭。
+func (a *App) Run() {
+	// 通用壳：先加载 exe 同目录 resources/config.json 覆盖窗口与后端配置
+	//（CLI build 时写入；缺失则使用编译期/默认配置）。
+	// 配置存在但非法时打印告警（不中断启动），避免用户手改配置出错时静默无感。
+	if err := a.loadRuntimeConfig(); err != nil {
+		fmt.Printf("freedom: warning: %v\n", err)
+	}
+
+	html, err := a.resolveHTML()
+	if err != nil {
+		fmt.Printf("freedom: failed to resolve HTML: %v\n", err)
+		return
+	}
+
+	w := webview.New(a.cfg.Debug)
+	if w == nil {
+		fmt.Println("freedom: failed to create webview")
+		return
+	}
+	a.setView(w)
+	defer func() {
+		_ = a.backend.Close()
+		w.Destroy()
+	}()
+
+	// 进程后端：启动后端进程并把其推送的事件转发到前端。
+	if pb, ok := a.backend.(*ProcBackend); ok {
+		pb.OnEvent(func(event string, data interface{}) {
+			a.Emit(event, data)
+		})
+		if err := pb.start(); err != nil {
+			fmt.Printf("freedom: backend start failed: %v\n", err)
+			return
+		}
+	}
+
+	w.SetTitle(a.cfg.Title)
+	w.SetSize(a.cfg.Width, a.cfg.Height, webview.HintNone)
+	// 最小尺寸：任一项 >0 即生效；未设置的一项传 0 表示该维度不限制
+	//（GTK gtk_widget_set_size_request / Cocoa minSize 对 0 均视为"未指定"）。
+	if a.cfg.MinWidth > 0 || a.cfg.MinHeight > 0 {
+		w.SetSize(a.cfg.MinWidth, a.cfg.MinHeight, webview.HintMin)
+	}
+	a.applyCenter()
+	a.applyTitleBar()
+	a.setWindowIcon()
+
+	// 注入前端 SDK：window.freedom 全局对象。
+	w.Init(jsSDK)
+
+	// 绑定 IPC 桥接入口：前端 window.__freedom_bridge(method, paramsJson)。
+	// webview_go 的 Bind 会让前端调用返回 Promise，Go 侧结果自动 JSON 序列化回传。
+	if err := w.Bind("__freedom_bridge", a.bridge); err != nil {
+		fmt.Printf("freedom: failed to bind bridge: %v\n", err)
+		return
+	}
+	// 框架内置方法：健康检查。
+	if err := w.Bind("__freedom__ping", func() string { return "pong" }); err != nil {
+		fmt.Printf("freedom: failed to bind ping: %v\n", err)
+		return
+	}
+	// 框架内置方法：窗口控制（无边框模式下前端自绘按钮使用）。
+	// 支持动作：minimize / maximize / unmaximize / toggleMaximize / close / isMaximized / isFrameless。
+	if err := w.Bind("__freedom_window", a.windowControl); err != nil {
+		fmt.Printf("freedom: failed to bind window control: %v\n", err)
+		return
+	}
+
+	if a.onReady != nil {
+		a.onReady(a)
+	}
+
+	w.SetHtml(html)
+	w.Run()
+}
+
+// bridge 是前端调用后端的统一入口（JSON-RPC 风格）。
+// 前端 SDK 通过 window.__freedom_bridge(method, paramsJson) 调用，
+// 桥接层把请求转发给当前绑定的后端（内嵌 Go 方法或任意语言进程）。
+func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage, err error) {
+	// 防御后端方法 panic 导致整个窗口崩溃：统一转为错误回传前端。
+	defer func() {
+		if r := recover(); r != nil {
+			result = nil
+			err = fmt.Errorf("freedom: method %q panicked: %v", method, r)
+		}
+	}()
+
+	var params []json.RawMessage
+	if len(paramsJSON) > 0 && paramsJSON != "null" {
+		if err := json.Unmarshal([]byte(paramsJSON), &params); err != nil {
+			return nil, fmt.Errorf("freedom: method %q: invalid params: %w", method, err)
+		}
+	}
+
+	// 框架内置方法特判：__freedom__ping 由 webview Bind 注册为全局函数
+	// window.__freedom__ping()，同时兼容经 freedom.call()/__freedom_bridge 路由的旧写法，
+	// 避免模板"测试桥接"自检报"method not bound"。
+	if method == "__freedom__ping" {
+		return json.RawMessage(`"pong"`), nil
+	}
+
+	raw, err := a.backend.Handle(method, params)
+	if err != nil {
+		return nil, err
+	}
+	data, err := json.Marshal(raw)
+	if err != nil {
+		return nil, fmt.Errorf("freedom: method %q: cannot marshal result: %w", method, err)
+	}
+	return json.RawMessage(data), nil
+}
+
+// Emit 把事件推送到前端。前端通过 window.freedom.on(event, cb) 订阅。
+// 线程安全：可从任意 goroutine 调用（进程后端推送的事件亦经由本函数）。
+func (a *App) Emit(event string, data interface{}) {
+	v := a.getView()
+	if v == nil {
+		return
+	}
+	eb, _ := json.Marshal(event)
+	db, err := json.Marshal(data)
+	if err != nil {
+		db = []byte("null")
+	}
+	js := "window.freedom && window.freedom.emit(" + string(eb) + "," + string(db) + ");"
+	v.Dispatch(func() {
+		v.Eval(js)
+	})
+}
+
+// Quit 关闭窗口并退出应用。可从任意 goroutine 调用。
+func (a *App) Quit() {
+	if v := a.getView(); v != nil {
+		v.Dispatch(func() {
+			v.Terminate()
+		})
+	}
+}
+
+// WindowHandle 返回底层原生窗口句柄（Windows 上为 HWND）。
+func (a *App) WindowHandle() uintptr {
+	if v := a.getView(); v != nil {
+		return uintptr(unsafe.Pointer(v.Window()))
+	}
+	return 0
+}
+
+// windowControl 处理前端 window.freedom.window.* 的窗口控制请求。
+// 具体实现按平台分文件：window_windows.go（Windows）/ window_other.go（macOS、Linux）。
+func (a *App) windowControl(action string) (interface{}, error) {
+	return windowControl(a, action)
+}
+
+// resolveHTML 依据配置返回页面内容。
+// 优先级：exe 同目录 resources/index.html（预编译通用壳，CLI build 写入）> cfg.HTML > 内置占位页。
+func (a *App) resolveHTML() (string, error) {
+	if html, err := loadRuntimeHTML(); err == nil && html != "" {
+		return html, nil
+	}
+	if a.cfg.HTML != nil {
+		return a.cfg.HTML()
+	}
+	return defaultHTML, nil
+}

package/templates/go/webview_go/webview.go

@@ -165,10 +165,11 @@ type webview struct {
 }
 
 var (
-	m        sync.Mutex
-	index    uintptr
-	dispatch = map[uintptr]func(){}
-	bindings = map[uintptr]func(id, req string) (interface{}, error){}
+	m         sync.Mutex
+	index     uintptr
+	dispatch  = map[uintptr]func(){}
+	bindings  = map[uintptr]func(id, req string) (interface{}, error){}
+	bindNames = map[string]uintptr{} // name -> index，供 Unbind 清理 bindings 条目
 )
 
 func boolToInt(b bool) C.int {
@@ -261,8 +262,12 @@ func (w *webview) Dispatch(f func()) {
 	for ; dispatch[index] != nil; index++ {
 	}
 	dispatch[index] = f
+	// 在锁内保存局部副本再解锁：解锁后读取共享 index 属数据竞争
+	//（另一 goroutine 可能在 Lock 内推进 index），race detector 会报，
+	// 且极端时序下可能把未就绪的 index 传给 C 层导致回调失配。
+	idx := index
 	m.Unlock()
-	C.CgoWebViewDispatch(w.w, C.uintptr_t(index))
+	C.CgoWebViewDispatch(w.w, C.uintptr_t(idx))
 }
 
 //export _webviewDispatchGoCallback
@@ -364,14 +369,27 @@ func (w *webview) Bind(name string, f interface{}) error {
 	for ; bindings[index] != nil; index++ {
 	}
 	bindings[index] = binding
+	bindNames[name] = index
+	// 锁内保存副本，避免解锁后读取共享 index（与 Dispatch 同类数据竞争）
+	idx := index
 	m.Unlock()
 	cname := C.CString(name)
 	defer C.free(unsafe.Pointer(cname))
-	C.CgoWebViewBind(w.w, cname, C.uintptr_t(index))
+	C.CgoWebViewBind(w.w, cname, C.uintptr_t(idx))
 	return nil
 }
 
 func (w *webview) Unbind(name string) error {
+	// 清理 Go 侧 bindings / bindNames 条目，避免 Unbind 后永久泄漏。
+	// C 侧 binding_context（glue.c calloc，每 Bind 约 16B）在 C++ unbind 中
+	// 仅 erase map 不 free，会小幅泄漏；但框架内 Bind 次数固定（3~4 个）、
+	// 进程生命周期内不会反复 Bind/Unbind，实际影响可忽略，故不额外改 C 层。
+	m.Lock()
+	if idx, ok := bindNames[name]; ok {
+		delete(bindings, idx)
+		delete(bindNames, name)
+	}
+	m.Unlock()
 	cname := C.CString(name)
 	defer C.free(unsafe.Pointer(cname))
 	C.CgoWebViewUnbind(w.w, cname)