Wails v2 中 React 项目需手动初始化（如 Vite/CRA），配置 wails.json 的 distDir 和 devServerURL，确保 npm run build 先执行且路径匹配，调用 Go 函数前等待 window.wailsBridgeReady，参数须 JSON 可序列化，错误通过 err.message 获取。
Wails v2 中 React 项目如何正确初始化并连接 Go 后端
Wails v2 默认使用 wails init 生成 Vue 模板，直接选 React 会失败或生成不完整结构。必须手动初始化 React（推荐用 create-react-app 或 vite），再通过 wails build -p ./frontend 显式指定前端路径。
关键点在于：Wails 不接管 React 构建流程，只负责把构建产物（dist/）注入到桌面窗口中。因此 npm run build 必须先成功执行，且输出目录需与 wails.json 中的 frontend:distDir 一致（默认是 frontend/dist）。
- 用
vite create react-app初始化时，务必选择 JavaScript（非 TypeScript），否则 Wails 的默认构建可能因缺少@types/react报错 -
wails.json中的frontend:devServerURL要设为http://localhost:5173（Vite）或http://localhost:3000（CRA），否则热重载失效 - React 中调用 Go 函数前，必须等
window.wailsBridgeReady触发（Wails 注入脚本完成），不能在useEffect(() => {}, [])里直接调用window.backend.xxx()
如何从 React 调用 Go 定义的函数（含参数传递与错误处理）
Go 端导出函数必须满足：首字母大写、接收指针参数（*wails.App）、返回 error。Wails 会自动将其挂载到 window.backend 下。
例如 Go 定义了 func (a *App) GetUserInfo(id int) (map[string]interface{}, error)，React 中应这样调用：
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
try {
const data = await window.backend.GetUserInfo(123);
console.log(data);
} catch (err) {
console.error("Go call failed:", err.message); // err.message 是 Go 中 error.Error() 的返回值
}
- 所有参数必须是 JSON 可序列化类型（
string,number,boolean,object,null），不支持Date,Function,undefined或循环引用对象 - Go 函数返回的
error会被转成 JSError实例，err.message对应 Go 中err.Error()；若需额外上下文，可在 Go 中返回fmt.Errorf("code: %d, msg: %s", code, msg) - 异步调用是强制的——
window.backend.Xxx()总是返回 Promise，不可同步等待
React 开发时如何避免白屏、跨域和热更新失效
白屏最常见原因是前端资源路径不对：Vite/CRA 默认输出的 index.html 中 <script> 和 <link> 引用的是相对路径（如 /assets/index.xxxx.js），但 Wails 开发服务器提供的是根路径 http://localhost:34115/，导致 404。
- 解决方法：在 Vite 项目中设置
base: "./"（vite.config.ts），CRA 则在package.json加"homepage": "./" - 禁用 CRA 的代理（
proxy字段），它会干扰 Wails 的 devServerURL；Wails 自己通过frontend:devServerURL控制请求转发 - 确保
wails dev和npm run dev（或pnpm dev）同时运行，且端口不冲突；Wails 默认监听 34115，React 开发服务器不要占这个端口 - 如果热更新卡住，检查浏览器控制台是否报
Failed to load resource: net::ERR_CONNECTION_REFUSED——说明devServerURL配错了，或者前端服务根本没起来
构建生产版本时 wails build 找不到 dist 文件的排查路径
错误信息通常是：ERROR: frontend dist directory does not exist: ./frontend/dist。这不是 Wails bug，而是构建顺序或路径配置问题。
- 先确认
cd frontend && npm run build是否真生成了frontend/dist/index.html；部分模板（如 Vite + React）默认输出到dist，但 Wails v2.9+ 期望的是frontend/dist，不是frontend/build - 检查
wails.json中frontend:distDir是否为"frontend/dist"（注意斜杠方向，Windows 也用正斜杠） - 如果用了 pnpm，
pnpm run build可能因 workspace 链接导致输出路径异常，建议改用npm run build或显式指定--outDir - CI/CD 中构建失败常因未安装前端依赖：必须在
wails build前执行cd frontend && npm ci（而非npm install）
真正麻烦的从来不是“能不能连上”，而是前端构建产物的路径、静态资源 base URL、以及 Go 和 JS 之间那层隐式约定的序列化边界——这三个地方错一个，整个通信链就静默失败。
