buffalo dev启动失败时先查go mod tidy是否成功、npm install是否完成、database.yml中development的host和port能否连通。

buffalo dev 启动失败时先查哪三件事

90% 的启动失败不是代码问题，而是环境链路断在前几步。别急着改 handler，先确认这三项是否就绪：

• go mod tidy 是否成功执行——buffalo dev 依赖 github.com/gobuffalo/pop/v6 等子模块，仅靠 go.mod 声明不够，缺失会导致 panic: unknown dialect
• npm install（或 yarn install）是否完成——即使你删了 assets/，buffalo dev 默认仍尝试调用 webpack，找不到 node_modules 会直接退出，报错类似 exec: "npm": executable file not found
• database.yml 中 development 区块的 host 和 port 能否连通——用 telnet localhost 5432 或 nc -zv 127.0.0.1 3306 实测，别只看配置文件写没写对

模板渲染报 template not found 怎么快速定位

这不是路径写错了，是 Buffalo 的查找逻辑和你直觉不一致。它不扫描、不模糊匹配，只按严格约定找：

• r.HTML("admin.dashboard") → 对应 templates/admin/dashboard.html，点号 = 目录分隔，r.HTML("admin/dashboard.html") 必然失败
• 文件名必须全小写：Dashboard.html ≠ dashboard.html，Linux 环境下直接 404
• 启动时加 app.PrecompileTemplates()（放在 App() 函数 return 前），它会在 buffalo dev 启动阶段一次性校验所有模板路径，报错如 template "users/edit.html" not found，而不是等用户点击才 panic

数据库迁移失败后 rollback 不生效怎么办

buffalo db rollback 不是“撤销上一条 SQL”，而是回退到上一个迁移版本（version）。如果失败，大概率是状态记录不一致：

Buffalo框架 1.0.1

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

下载

• 检查 migrations/ 下最新迁移文件名是否含时间戳（如 20230101120000_create_users.up.fizz），Buffalo 依赖文件名排序，手动重命名或乱序会导致版本识别错乱
• 运行 buffalo db migrate -v 查当前版本，再对比 pop_migrations 表中 version 字段是否一致；若表里有记录但文件已删，需手动 DELETE FROM pop_migrations WHERE version = 'xxx'
• rollback 只执行 .down.fizz 或 .down.sql，如果该文件为空或写错（比如漏掉 DROP TABLE），命令看似成功，实际没变化

升级 Buffalo 版本后 build 失败常见卡点

Buffalo 1.x 之后移除了对 packr v1 的支持，但旧项目残留生成物会干扰新流程：

• 删掉项目根目录下的 packrd.go 和 packr2 目录（如有），再执行 packr2 clean && packr2
• 确认 main.go 顶部有 //go:generate packr2 注释，缺了这行 buffalo build --static 会跳过资源打包，导致 /assets/app.css 404
• 检查 go.mod 中 github.com/gobuffalo/buffalo 和 github.com/gobuffalo/packr/v2 版本是否匹配——例如 Buffalo v1.0.1 要求 packr/v2 v2.8.3+，低版本会编译报错 undefined: packr.New

维护 Buffalo 项目最耗时的不是写新功能，而是每次环境变更或版本升级时，那些没显式声明却隐式依赖的环节：模板路径约定、迁移文件命名规则、packr 构建标记、甚至 npm install 的存在本身。它们不报错，直到某天 buffalo dev 静默退出。