Buffalo项目启动失败主因是CLI未正确安装、数据库未初始化或database.yml配置错误：需先用go install安装CLI并验证buffalo version，再依次执行go mod tidy、npm install、buffalo db create与migrate，最后确保database.yml中dialect、host、user等字段准确且数据库服务已运行。
Buffalo 项目跑不起来，八成卡在安装或调试流程的某个环节——不是 CLI 没装对，就是 buffalo dev 启动前漏了数据库初始化，又或者 database.yml 配错导致迁移直接 panic。整个流程环环相扣，跳一步就断。
buffalo CLI 安装失败的三个典型信号
执行 buffalo version 报 command not found，说明 CLI 根本没进 PATH；输出 cannot find module providing package，基本是 Go 版本低于 1.21 或 GOPROXY 没配；而 buffalo version 能运行但显示 v0.17.x 或更低，说明你装的是旧版 CLI（比如从 brew 或旧文档抄的命令），必须换成 go install github.com/gobuffalo/cli/cmd/buffalo@latest。
安装后新开终端再验证，别在当前 shell 里反复 source —— $GOPATH/bin 不在 PATH 里，buffalo 就永远找不到。
buffalo dev 启动即退出的常见原因
buffalo dev 启动几秒后自动退出，通常不是代码问题，而是前置条件缺失：
-
go mod tidy没跑完：models 依赖 pop/v6、buffalo 等模块未补全，models.NewDB()会 panic -
npm install被跳过：即使不用前端，buffalo dev默认尝试构建 assets，找不到node_modules就直接 abort -
buffalo db create和buffalo db migrate没执行：表不存在，任何 action 查询都会触发table not found错误并终止服务
注意：这三步顺序不能乱，migration 必须在 create 之后，否则报 database does not exist。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
database.yml 配错导致连接拒绝却不报具体字段
报错 dial tcp 127.0.0.1:5432: connect: connection refused，第一反应不是改 YAML，而是先确认 PostgreSQL 进程是否真在监听——pg_ctl status 或 systemctl is-active postgresql 更可靠。确认服务起来后，再核对 database.yml：
-
dialect必须写"postgres"，不是"postgresql"或"pg" - PostgreSQL 的
host写"localhost"没问题，但 MySQL 的host强烈建议用"127.0.0.1"，避免 Unix socket 解析失败 -
user和password必须跟本地数据库实际账号一致；若用默认postgres用户但没设密码，password字段得留空字符串""，不能删掉该行
配置改完别急着重试，先手动用 psql -h localhost -U postgres -d myapp_development 验证连通性。
热加载失效时怎么快速定位监听路径
改了 actions/home.go 没反应，终端没输出 Building...，说明文件变更根本没被检测到。优先检查：
- 是否存在
buffalo.dev.yml？如果存在，YAML 缩进是否全是两个空格？多一个 tab 或少一个空格都会让整个配置静默失效，退回到默认监听规则 - 是否用了
--watch-dir参数但路径写错？比如想监控./ui却写了ui/（缺前导点） - 是否在 WSL 或 Docker 环境下运行？某些文件系统事件（inotify）在挂载目录中不可靠，可临时加
--poll参数启用轮询模式
最简单的验证方式：删掉 buffalo.dev.yml，用纯命令行启动 buffalo dev --port 4000，看基础监听是否恢复——能恢复，问题就出在配置文件上。
