Wails init失败需先检查Node.js和npm版本，换淘宝镜像；Go方法需结构体绑定+//wails:export注释，参数返回值受限；前端须在wails.ready()后调用；构建时注意cgo依赖与系统环境。
Wails init 项目失败：npm install 报错或卡住怎么办
Wails 依赖 Node.js 生态，wails init 本质是调用 npm install 安装前端构建依赖。国内用户常遇到超时、404 或 node-gyp 编译失败。
- 先确认
node -v≥ 18.17.0（Wails v2.9+ 要求），npm -v≥ 9.6.0；旧版本会静默失败 - 换淘宝镜像：
npm config set registry https://registry.npmmirror.com，再重试wails init - 若仍卡在
electron-builder或sharp，临时跳过可选依赖：wails init -n myapp --skip-frontend-install，后续进frontend/手动npm install --no-optional - Windows 用户注意：必须安装
windows-build-tools（npm install --global windows-build-tools）或启用 WSL2 后用 Linux 环境初始化
Go 端如何暴露方法给前端调用：结构体绑定与参数限制
Wails 不支持直接导出函数，必须通过结构体方法 + //wails:export 注释声明。方法签名有硬性约束，否则运行时报 Method not found 或 panic。
- 接收者必须是值类型或指针类型，但不能是接口或嵌套指针（如
*map[string]int） - 参数和返回值只能是基础类型、结构体（字段首字母大写）、切片、map（key 必须是 string 或基本类型），不支持 channel、func、unsafe.Pointer
- 结构体字段需加
json:标签才能被前端正确序列化，例如：type App struct { Name string `json:"name"` } - 调用前务必在
main.go中注册：wails.Run(&App{})，不是new(App)或&App{}（后者可能触发 GC 提前回收）
前端调用 Go 方法时提示 “not a function” 或 Promise pending 不 resolve
这是最常见集成断裂点：前端代码看似调用成功，实际没走 Go 层。根本原因通常是 JS 运行时机或上下文错误。
-
wails.bridge不是全局变量，必须等wails.ready()回调后才能使用，否则window.backend未挂载 - 确保前端代码在
mounted()（Vue）或useEffect(() => {}, [])（React）中调用，而不是组件定义时执行 - 检查浏览器控制台是否有
Uncaught (in promise) Error: Method not found—— 对应 Go 方法名拼写是否与前端调用一致（大小写敏感，且不含包名） - 如果返回值含时间戳、浮点数等易失精度类型，前端需用
JSON.parse(JSON.stringify(...))深拷贝，避免 Wails 内部复用对象引用导致意外修改
构建 Windows/macOS/Linux 可执行文件：cgo 和 CGO_ENABLED 的坑
wails build 默认启用 cgo，但交叉编译或 CI 环境下极易因缺失系统库或头文件失败，尤其涉及 SQLite、图像处理等场景。
立即学习“go语言免费学习笔记（深入）”；
- macOS 上构建失败常见于 Xcode 命令行工具未安装：
xcode-select --install - Linux 构建需提前装
libgtk-3-dev libwebkit2gtk-4.0-dev（Ubuntu/Debian）或对应包；CentOS 需webkit2gtk4.0-devel - 若项目不含 C 依赖，强制禁用 cgo 可大幅简化构建：
CGO_ENABLED=0 wails build -p，但会丢失sqlite、net/http的系统 DNS 解析等能力 - Windows 下用 MinGW 构建时，确保
CC环境变量指向x86_64-w64-mingw32-gcc，而非 MSVC 工具链（Wails 不兼容）
json: 标签漏写、一次 CGO_ENABLED=0 误用，都可能导致应用启动黑屏或调用静默失败。调试时优先看终端日志（wails dev 输出）和浏览器 Console，而不是直接改构建参数。 
