go项目部署需打通静态资源编译、嵌入与gin服务三步：确保goroot/gopath/goproxy环境变量正确；前端构建输出成品至static/，再用go:embed嵌入；gin中用staticfs配合绝对路径或embed.fs挂载，注意路径匹配与前缀问题。
Go 环境能跑起来，go run main.go 不报错，只是第一步；真正卡住人的，是静态资源（JS/CSS/HTML）怎么编译、怎么打进二进制、怎么在 Gin 里正确服务——这三步没串通，项目就只能本地开发，没法部署。
go env 检查必须过这三项
不是只要 go version 能输出就行。很多问题其实源于环境变量没设对，尤其在国内网络下：
-
GOROOT必须指向 Go 安装根目录（如/usr/local/go），不能和GOPATH混； -
GOPATH已非必需（Go 1.16+ 默认启用 module 模式），但若用了旧项目结构，它必须包含src、bin、pkg子目录； -
GOPROXY建议设为https://goproxy.cn,direct，否则go get github.com/gin-gonic/gin可能超时或 404。
验证命令：go env GOROOT GOPATH GOPROXY。输出为空或路径错误，就得回退到 shell 配置文件里补上 export 行。
静态资源编译不能直接写在 static/ 下
很多人把 static/js/index.ts 直接放进去，再用 go:embed 加载——结果运行时报错 file not found 或加载空白。因为 go:embed 只读取构建时已存在的文件，不执行编译。
- 前端源码（
.ts、.scss）应放在frontend/src/； - 构建命令（如
npm run build）输出到static/，且只放成品（static/js/bundle.js、static/css/app.css）； - 务必在
go build前完成构建，否则go:embed static/**会嵌入空目录或旧文件。
推荐用 //go:generate npm run build && go run embed.go 放在 main.go 顶部，配合 go generate 统一触发。
Gin 中静态服务路径容易配反
常见写法 r.Static("/static", "./static") 看似合理，但上线后常 404——因为生产环境二进制运行时工作目录不一定是项目根目录。
- 用
os.Executable()获取二进制路径，再filepath.Dir()得到目录，拼出绝对路径传给Static； - 更稳妥的是用
go:embed+gin.SetHTMLTemplate或http.FileServer配合http.FS； - 如果用了
embed.FS，别忘了在main.go顶部加//go:embed static/*，且路径必须匹配嵌入声明（比如static/**才能包含子目录）。
示例关键片段：
var staticFS embed.FS //go:embed static/*
...
r.StaticFS("/static", http.FS(staticFS))
注意：这里 /static 是 URL 路径，staticFS 是嵌入的文件系统，二者语义不同，不能互换。
嵌入资源后调试困难，别跳过这一步
打包进二进制后，static/ 文件不可见、无法实时修改——但你仍需要确认哪些文件被嵌入、大小是否异常、路径是否带多余前缀。
- 用
go tool dist list -f '{{.OS}}/{{.Arch}}'确认目标平台，避免本地构建后在 Linux 服务器上运行失败； - 加一行
fmt.Printf("embedded files: %+v\n", fs.Glob(staticFS, "static/**"))在启动时打印，验证嵌入内容； - 如果 CSS/JS 404，先检查浏览器 Network 标签里请求路径是否多了一级
static/static/...——那说明嵌入路径写成了./static/**，而StaticFS又挂载在/static，导致双重前缀。
最常被忽略的点：嵌入声明里的路径是相对于 main.go 的，不是相对于项目根；而 go:embed 不支持 ../ 向上跳转，所以 static/ 必须和 main.go 在同一级或子目录。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
