必须先安装buffalo cli再执行buffalo new，顺序不可颠倒；需go≥1.21（推荐1.26.0），确认go version与gopath有效，用go install安装后将$gopath/bin加入path，验证buffalo version；项目须在空目录创建，首次运行前必执行go mod tidy、npm install、buffalo db create && migrate。
必须先装 CLI，再用 buffalo new，顺序错或跳步都会失败。
安装 buffalo CLI 工具前要确认 Go 环境
执行 go version，输出必须是 go1.21 或更高；低于这个版本，go install 会报错或生成不可用的二进制。如果没装 Go，请去 go.dev/dl/ 下载 1.26.0（当前最稳兼容版）。
运行 go env GOPATH，确保有输出路径——这是 go install 默认放 buffalo 二进制的位置。若为空，需手动设置 GOPATH 并加入 PATH。
执行安装命令：go install github.com/gobuffalo/cli/cmd/buffalo@latest
⚠️ 常见失败原因：
- 提示 cannot find module providing package：Go 版本太低，或 GitHub 访问受限（可配 GOPROXY）
- buffalo version 报 command not found：$GOPATH/bin 没进系统 PATH，不是工具没装好，是 shell 找不到它
创建项目必须在空目录下运行 buffalo new
不能在已有 Go 模块、Git 仓库或含 go.mod 的目录里执行该命令，否则直接退出并报错。
新建空目录并进入：mkdir myapp && cd myapp
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
生成项目：buffalo new myapp
若只需 API 服务（不带前端资源和模板），加 --api 标志：buffalo new myapp --api
生成后检查关键文件：
- actions/app.go：主应用配置入口
- models/models.go：数据库连接逻辑，注意它不读 database.yml
- buffalo.dev.yml：开发服务器配置，修改后需重启 buffalo dev 才生效
- go.mod：已锁定依赖版本，别手动改
首次运行前必须补全三步，缺一不可
buffalo dev 不会自动帮你做这些事，少一步就 panic 或 404：
-
go mod tidy：拉取所有子依赖（比如github.com/gobuffalo/pop/v6），仅靠go.mod声明不够 -
npm install（或yarn install）：构建前端资源必需，跳过会导致/assets/路径 404 -
buffalo db create && buffalo db migrate：初始化数据库并跑迁移，否则访问首页时因models.User查询失败而崩溃
执行完这三步，再跑 buffalo dev 才算真正能打开 http://localhost:3000。
容易被忽略的关键点
database.yml 是个“说明书”，Buffalo 运行时不读它；真实连接由 models.NewDB() 决定，通常靠 APP_DATABASE_URL 环境变量驱动。很多人卡在数据库连不上，其实是环境变量没设，而不是 YAML 文件写错了。
另外，buffalo dev 启动后终端输出的实际地址可能不是 :3000——端口冲突时它会自动换，但不会静默跳过，务必看最后一行日志里的 Starting application at http://...。
