Wails 项目初始化后 main.go 报错 “undefined: wails.Run”
这是最常见的起步卡点：Wails v2 和 v1 的入口函数完全不同，直接套用旧教程代码会编译失败。
Wails v2（当前稳定版）不再提供全局 wails.Run 函数，而是要求你显式构建 *wails.App 实例并调用其 Run() 方法。
- 确认你安装的是 Wails v2：
wails version输出应含v2.x.x - 删掉类似
wails.Run(...)的调用，改用app := wails.NewApp(&options)+app.Run() -
github.com/wails-app/wails/v2/pkg/options是必须导入的包，漏掉会导致options.App等类型未定义
前端调用 Go 函数时提示 “Method not found” 或控制台报 Cannot read property 'xxx' of undefined
根本原因不是函数没写，而是 Go 函数未被正确暴露给前端——Wails v2 默认不自动注册任何方法，必须手动绑定。
暴露函数的关键是：在 wails.NewApp() 的 options.Bind 字段中传入一个包含可导出方法的结构体实例。
立即学习“go语言免费学习笔记（深入）”；
- Go 函数必须是**导出的（首字母大写）**，且接收指针接收者（如
func (a *App) GetData() string） -
options.Bind必须传入指向该结构体的指针：Bind: &App{}，传值或 nil 都会静默失效 - 前端调用路径固定为
window.backend.<StructName>.<MethodName>，比如window.backend.App.GetData() - 如果结构体名是
App，但你在Bind里传了&MyApp{}，前端就要用window.backend.MyApp.GetData()
开发时热重载（wails dev）不生效，修改 Go 代码后页面无反应
Wails v2 的热重载只监听 Go 源码变更并自动 rebuild 二进制，但不会自动刷新浏览器——它依赖前端是否启用了自己的 HMR（如 Vite/Vue/React），且需正确配置代理。
常见断点在前端工程的开发服务器配置上，而非 Wails 本身。
- 确保前端项目已运行（如
npm run dev），且监听端口（如http://localhost:3000）能正常访问 - 检查
wails.json中"frontend:dev:server"是否指向该地址，例如："http://localhost:3000" - 若前端用 Vite，需在
vite.config.ts中设置server.host: true并允许跨域（Wails dev server 会代理请求） - 修改 Go 代码后终端应显示
Rebuilding app...，若无此输出，说明文件未被监听（检查是否在go.mod同级目录下执行wails dev）
打包后双击运行闪退，Windows/macOS/Linux 表现不一致
打包产物依赖系统级 WebView 运行时，而各平台默认行为差异极大——尤其是 Windows 上，没有预装 Edge WebView2 的老系统会直接崩溃，且无错误提示。
这不是代码 bug，而是部署环境缺失。解决方案必须按平台区分处理。
- macOS：需在
wails.json中设置"build:bundleID"，否则签名失败导致无法启动（Apple Gatekeeper 拦截） - Windows：必须确认目标机器已安装 WebView2 Runtime；或改用
wails build -f打包“带运行时”的版本（体积增大 ~150MB） - Linux：多数发行版需手动安装
webkit2gtk-4.1（Ubuntu/Debian）或webkit2gtk4.1（Fedora），否则报libwebkit2gtk-4.1.so.0: cannot open shared object file
最稳妥的验证方式：在目标系统干净虚拟机中解压安装包，双击前先终端运行一次，看是否有具体 panic 或 missing library 错误输出。
