Go前后端混合项目核心是分工明确、轻量集成：后端用Go提供API和静态服务，前端用Vite等开发并构建至dist，再通过embed打包进二进制实现单文件部署；开发时前端本地热更新、Go代理API请求，生产时Go托管dist并处理SPA fallback路由。
Go 本身不区分“前端”或“后端”环境——它只提供一个稳定、跨平台的运行时和工具链。所谓“前后端通用”的 Go 环境，是指既能支撑你写 API 服务（net/http、gin、echo），又能配合前端构建产物（dist/）做静态托管或嵌入式部署，且不干扰 Node.js 的存在。关键不是让 Go 做前端，而是让它不跟前端抢活、不制造冲突。
go 命令能跑，node 命令也能跑，才是真通用
很多团队卡在第一步：Go 和 Node.js 共存时，go 找不到，或 npm 报错“command not found”。这不是 Go 的问题，是 PATH 冲突或安装方式混用导致的。
- Windows 用户别用
msi装 Go 又用choco装 Node —— 两者都往PATH写，容易覆盖；建议统一用winget install Go+winget install OpenJS.NodeJS - macOS 用户避免
brew install go和brew install node同时用，尤其当 Homebrew 自动升级了openssl或icu4c，可能让go build链接失败；推荐 Go 用官网.pkg，Node 用nvm管理版本 - Linux（含统信 UOS）用户优先走 APT 安装
golang（UOS 自带源已适配），Node 则用nodesource源或直接解压二进制到$HOME/.local，再加进~/.bashrc的PATH，避开系统级路径污染
验证是否真正共存：新开终端，执行 go version && node -v && npm -v 三者必须一次性输出，中间不能报错。
vite.config.ts 里 proxy 是开发阶段唯一需要改的 Go 相关配置
前端工程（Vite/React/Vue）和 Go 后端在开发时必须分离运行：前端跑在 http://localhost:5173，Go 跑在 :8080。此时所有 /api/xxx 请求必须由 Vite 代理过去，而不是让 Go 开 CORS 中间件去“兼容前端”。
立即学习“go语言免费学习笔记（深入）”；
-
server.proxy必须匹配 Go 路由前缀，比如 Go 注册的是r.HandleFunc("/api/users", handler)，那 Vite 就得配'/api': { target: 'http://localhost:8080' } - 不要设
changeOrigin: false，否则 Go 收到的Host头还是localhost:5173，某些鉴权逻辑会误判 - 避免在 Go 里写
Header().Set("Access-Control-Allow-Origin", "*")—— 这会让浏览器拒绝带凭证（cookie / auth header）的请求，而代理模式下根本不需要它
代理只在 vite dev 时生效；构建后的 dist/ 交给 Go 托管，此时不再走代理，也不需要 CORS。
go.mod 初始化和 GOPROXY 必须在项目根目录手动执行
前后端混合项目里，Go 后端代码通常在 backend/ 子目录，但 go mod init 不能在 backend/ 下随便执行——它决定模块路径，也影响后续 embed.FS 加载 dist/ 的相对路径解析。
- 如果最终要打包整个项目（含前端构建产物），
go mod init应该在项目最外层目录运行，例如myapp/，模块名就设为myapp；这样backend/main.go里写//go:embed dist/*才能正确指向myapp/dist/ -
go env -w GOPROXY=https://goproxy.cn,direct必须全局执行一次，否则go get会卡在proxy.golang.org；国内 CI/CD 流水线尤其容易漏这步 - 不要依赖 IDE 自动初始化
go.mod—— VS Code 的 Go 插件有时会在错误目录触发，生成的module名带vendor或临时路径，后续embed读取失败时错误信息极不直观
执行完后检查 go.mod 第一行：module myapp（不是 module backend，也不是 module .）。
http.FileServer 托管 dist 时 fallback 路由容易漏掉 index.html
Go 用 http.FileServer 托管前端构建产物，目标是让 /user/profile 这类 SPA 路由也能返回 index.html，而不是 404。但标准 FileServer 不做 fallback，必须自己 wrap。
- 别用
http.ServeFile(w, r, "dist/index.html")硬编码——它只响应根路径，子路径全挂 - 正确做法是用
http.StripPrefix+ 自定义http.Handler拦截 404，再查dist/index.html；或者直接上github.com/gorilla/handlers的NotFoundHandler - 如果用了
embed.FS，fallback 必须基于fs.ReadFile检查文件是否存在，而不是os.Stat—— 因为 embed 的文件不在磁盘上，os.Stat永远返回 error
最容易被忽略的一点：fallback 逻辑必须放在所有 API 路由注册之后，否则 /api/xxx 请求可能被当成静态资源兜底，返回 HTML 而不是 JSON。
