脚手架项目必须设为 module root：新建空目录执行 go mod init github.com/yourname/my-scaffold，入口用 cmd/my-scaffold/main.go，模板用 embed.FS+text/template，发布需打 v0.1.0 标签并验证跨平台生成。
脚手架项目必须设为 module root
Go 脚手架不是普通库，它要能被 go install 安装、被其他项目调用生成代码，所以整个骨架本身得是一个可独立构建的 module。不能放在某个大仓库的子目录里直接开干——那样 go mod init 会出错，后续 go install 也找不到入口。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 新建空目录，比如
my-scaffold，cd 进去再执行go mod init github.com/yourname/my-scaffold - 模块名必须是完整 URL 形式（哪怕你没真 push 到 GitHub），否则
go install无法解析路径 - 如果将来要支持私有 registry 或本地开发调试，建议在
go.mod顶部加//go:build !prod注释并配replace，但生产发布前务必删掉replace行
命令行入口用 cmd/main.go 而非 main.go 直接放根目录
Go 模块中，只有 cmd/xxx 下的包才能被 go install 构建成可执行文件。把 main.go 放根目录会导致 go install . 报错：no Go files in ...（因为根目录默认是 library 包）。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 结构固定为：
cmd/my-scaffold/main.go，其中main()函数负责解析 flag、调用模板引擎、写入目标路径 - 业务逻辑（如模板渲染、目录结构生成）全部抽到
internal/generator/或pkg/scaffold/，避免 cmd 包膨胀 - 别在
main.go里硬编码路径或模板字符串——这些应该来自配置文件或 flag，默认值也要可覆盖
模板渲染必须用 text/template 而非字符串拼接
脚手架核心是生成代码，而 Go 原生 text/template 支持嵌套、条件、循环、自定义函数，且能安全转义（比如防止 Go 源码里出现未闭合的 {{）。手动字符串拼接极易漏掉换行、缩进错乱、变量注入漏洞。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 模板文件统一放
templates/目录下，用embed.FS打包进二进制（Go 1.16+），避免运行时依赖外部文件路径 - 加载时用
template.ParseFS(templatesFS, "templates/**/*")，而不是template.ParseFiles - 给模板加
funcMap：比如"toLower": strings.ToLower、"snakeCase": strcase.ToSnake（需引入github.com/stoewer/go-strcase），但禁止在模板里调用os.WriteFile这类副作用函数
go install 失败常见原因和验证步骤
很多开发者卡在最后一步：本地 go install 成功，但别人 go install github.com/yourname/my-scaffold@latest 报错。根本原因是 GOPROXY 或版本 tag 问题，不是代码逻辑问题。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 发布前必须打 git tag，格式为
v0.1.0（带v前缀），否则@latest无法命中 - 确认
go.mod第一行 module 名与 git 仓库地址完全一致（大小写、.git 后缀都不能错） - 本地验证：删掉
$GOPATH/bin/my-scaffold，执行GOBIN=$(pwd)/bin go install github.com/yourname/my-scaffold@v0.1.0，看是否生成可执行文件 - CI 流水线里加
go list -m -f '{{.Dir}}' github.com/yourname/my-scaffold，确保模块能被正确 resolve
真正麻烦的是跨平台模板路径处理和 Windows 下的文件权限继承——这些不会报编译错误，但生成的项目跑不起来。动手前先在 macOS、Linux、Windows 上各跑一遍 my-scaffold new demo，别只信 CI 里的 Linux 环境。
