Buffalo不是“装完就能跑”的框架，90%新手失败源于Go版本（须1.23.x/1.24.x）、GOPATH清空、DATABASE_URL与GO_ENV环境变量三者未同时满足；必须go install安装CLI、在空目录执行buffalo new --api、运行go mod tidy/npm install/数据库迁移后，buffalo dev才真正启动。
Buffalo 不是“装完就能跑”的框架，新手卡在 buffalo new 或 buffalo dev 报错，90% 是环境没对齐——Go 版本、GOPATH、DATABASE_URL 三者必须同时满足约束，缺一不可。
Go 环境和 Buffalo CLI 安装必须手动 go install
别用 Homebrew、Scoop 或预编译二进制。它们能跑 buffalo version，但 buffalo new 会因缺失 go mod 调用能力或 npm 集成而失败。
- 确认 Go 是
1.23.x或1.24.x：go version输出必须匹配，1.22或1.25会静默 panic - 清空
GOPATH：Linux/macOS 执行unset GOPATH；Windows 用户禁用 GOPATH 模式（控制面板 → 系统 → 高级 → 环境变量中删掉 GOPATH） - 安装 CLI：
go install github.com/gobuffalo/cli/cmd/buffalo@latest - 验证 PATH：
buffalo version应输出类似v1.0.1；若提示command not found，把$GOBIN（默认$GOPATH/bin）加进$PATH
初始化项目必须在空目录 + 手动配 DATABASE_URL
buffalo new 不读 config/database.yml，也不接受已有 go.mod 的目录。它直接根据当前路径名生成 module 名，并硬编码进 go.mod —— 目录名含点（.）、大写或空格都会导致后续 go build 失败。
- 新建空目录：
mkdir myapp && cd myapp（推荐全小写 + 连字符，如blog-api） - 生成项目：
buffalo new myapp --api（加--api跳过前端模板，降低新手干扰） - 立刻导出环境变量：
export DATABASE_URL="sqlite://./development.sqlite"（SQLite 最简起步）或 PostgreSQL/MySQL 对应 URL - 必须导出
GO_ENV：export GO_ENV=development，Buffalo 不自动加载.env
启动服务前必须跑通三步依赖链
buffalo dev 不是单命令启动器，它隐式依赖 go mod tidy、npm install 和数据库连接就绪。漏掉任一环，终端只会卡在 Building... 或报 no primary key defined。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 执行
go mod tidy：拉取 Buffalo 及其依赖（包括pop/v6） - 执行
npm install：即使用了--api，Buffalo 启动时仍会尝试构建 assets，没node_modules会 panic - 建库并迁移：
buffalo db create && buffalo db migrate（SQLite 无需提前建库，但命令必须执行） - 启动：
buffalo dev；终端最后一行显示Starting application at http://127.0.0.1:3000才算真正跑起来——端口被占时它会自动递增，但不提示最终端口
写第一个 JSON 接口要绕开模板默认逻辑
Buffalo 默认为全栈 MVC 设计，c.Render() 会触发 HTML 渲染流程。新手想写个 GET /ping 返回 {"ok": true}，直接写 c.Render(200, r.JSON(data)) 很可能 panic：因为 templates/ 目录不存在，或中间件（如 CSRF、session）未初始化。
- 删掉
templates/和public/目录（避免渲染器 fallback 或静态路由干扰） - 注释掉
app.Use(csrf.New())、app.Use(session.Middleware())等非 API 必需中间件 - 在
app.go中显式注册路由：app.GET("/ping", func(c buffalo.Context) error { return c.JSON(200, map[string]bool{"ok": true}) }) - 不要用
r.Auto()或r.HTML()，纯 API 场景只认c.JSON()
最易被忽略的点：Buffalo 的 buffalo dev 是开发服务器，不是生产二进制；它会动态监听文件变更并重建，但不会自动重载 models/ 下的结构体字段变更——改了 User struct 后必须手动重启进程，否则 tx.Create() 可能 panic 报 “no primary key defined”。
