必须先安装buffalo cli，再执行new、拉依赖、建库、跑服务；安装失败主因是go版本低于1.21、$gopath/bin未加入path或网络无法直连github。

必须先装好 buffalo CLI，再初始化项目、拉依赖、建库、跑服务——四步缺一不可，跳过任意一步都会在 buffalo dev 阶段报错退出。

buffalo CLI 怎么装才不会 command not found

Buffalo 所有命令都依赖 CLI 工具，没它连 buffalo new 都执行不了。装的时候最容易卡在三处：

• Go 版本低于 1.21：运行 go version 确认，否则 go install 会失败
• $GOPATH/bin 没进系统 PATH：安装后新开终端，再跑 buffalo version；若仍提示 command not found，就手动把 $GOPATH/bin 加进 PATH
• 国内网络直连 GitHub 失败：加代理或改用预编译包，比如下载 buffalo_0.18.13_linux_amd64.tar.gz，解压后 chmod +x buffalo && sudo mv buffalo /usr/local/bin/

buffalo new 之后为什么 buffalo dev 启动失败

常见原因是项目没真正“活”起来：依赖没拉全、数据库没建、甚至 go.mod 都没初始化。别急着 dev，先做这三件事：

• 进项目根目录，执行 go mod tidy（补全 Go 依赖）和 npm install（前端资源，除非用了 --api）
• 确认本地 PostgreSQL 或 MySQL 已启动，端口通（telnet localhost 5432 测试）
• 执行 buffalo db create 创建数据库，再 buffalo db migrate 跑迁移——漏掉任一环节，buffalo dev 一访问页面就会 panic

buffalo dev 热加载不生效的几个硬性条件

buffalo dev 不是“写了就能热重载”，它依赖三个显式前提：

Buffalo框架 1.0.1

Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。

下载

• CLI 版本 ≥ v0.18.0（buffalo version 查看）
• 项目根目录存在 buffalo.dev.yml，或 main.go 中调用了 app.Serve()（新项目默认有）
• 修改的文件在监听范围内：actions/、models/、templates/、assets/；改 grifts/ 或配置文件不会触发重启

另外注意：端口被占时它会自动换端口，但终端输出的实际地址容易被忽略——请盯紧最后一行 Listening on http://127.0.0.1:XXXX，别默认还刷 :3000。

编辑器里 import 标红、跳转失效怎么办

VS Code 或 GoLand 里大片红色波浪线，不是 Buffalo 的锅，而是 Go 模块没被正确识别：

• 检查是否有 go.mod：没有就先 go mod init myapp（模块名必须和 import 路径一致）
• 确保 gopls 已安装并启用：VS Code 中按 Ctrl+Shift+P → “Go: Install/Update Tools”，勾全选
• 删掉项目里的 vendor/ 和 go.work：它们会干扰模块解析，Buffalo 项目只认 go.mod

最常被忽略的是模块名和 import 路径不一致——比如 go mod init myapp，但代码里写的是 import "github.com/user/myapp/actions"，这种错会导致整个项目无法索引。