Buffalo CLI 命令严格绑定上下文:buffalo db 仅支持 postgres/mysql/sqlserver(dialect名须一字不差),SQLite 被 pop v6+ 彻底移除;buffalo generate 不单独输出模板,需配合 resource/action 创建完整结构;buffalo test 忽略 -run 参数,单测必须用 go test -run ^TestName$ ./package。

Buffalo CLI 不是通用脚手架,它的每个命令都绑定明确上下文和约束条件;直接套用其他框架经验(比如 Rails 或 Django)会踩坑,尤其是 buffalo db、buffalo generate 和 buffalo test 这三类命令,参数错一位、环境缺一环,就静默失败或报“unknown dialect”“no app found”这类模糊错误。
buffalo db 命令只支持三种数据库,且 dialect 名必须一字不差
PostgreSQL、MySQL、SQL Server 是仅有的合法选项,SQLite 完全不被支持——不是配置写错了,而是 pop v6+ 彻底移除了 SQLite 驱动注册逻辑,database.yml 里写 dialect: sqlite3 或 DATABASE_URL=sqlite3://./dev.sqlite 全部无效。
- PostgreSQL 必须用
dialect: postgres(不是postgresql),连接串要带sslmode=disable,否则本地开发常连不上 - MySQL 必须用
dialect: mysql(不是mariadb或mysql8),还得显式加parseTime=true,否则time.Time字段扫描失败 - SQL Server 必须用
dialect: sqlserver(全小写、无横线),host不能填localhost(某些驱动下会解析成 Unix socket,得用127.0.0.1或具体 IP)
执行 buffalo db create 或 buffalo db migrate 时若卡住无输出、或 panic 报 driver: unknown driver "sqlite3",说明你正在试图绕过这个限制,别试了,换方案。
buffalo generate 不生成孤立模板,只随 resource/action 创建目录结构
buffalo generate 本身没有 “–template” 或 “–output-dir” 参数,它不会单独吐出一个 .html 文件。模板只在生成完整上下文时按约定路径连带创建。
- 运行
buffalo generate resource users name:string→ 自动建templates/users/目录,并生成index.html、show.html、new.html、edit.html和_form.html - 运行
buffalo generate action users#new→ 生成actions/users.go中的New方法 +templates/users/new.html(空文件) - 但加了
--api标志,如buffalo generate action --api api/v1 users#list→ 不创建任何模板,只建 handler 和路由
常见失败:执行完 generate resource 却没看到 templates/users/?先确认是否已运行 go mod tidy 拉取依赖——依赖缺失会导致模板目录生成阶段被跳过。
Buffalo框架 1.0.1 版本源码包下载,适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
buffalo test 不接受 -run 参数,单测必须直调 go test
buffalo test 只是封装了 go test ./,它完全忽略 -run、-v 等原生参数。执行 buffalo test -run TestHomeHandler 会静默忽略 -run,然后跑全量测试——这是最常被误用的点。
- 真想只跑一个函数,必须用原生命令:
go test -run ^TestHomeHandler$ ./actions - 函数名前后加
^和$是必须的,否则可能匹配到TestHomeHandlerWithAuth这类变体 - 路径
./actions要显式写出,不能省略;若测试在models/下,就得换成./models
容易 panic 的原因:测试函数里没初始化 app 实例(报 no app found)或 DB 配置未加载(报 failed to open database)。解决方式是在测试开头手动调 buffalo.TestEnv(),或改用 buffalo.Request 构造假请求绕过真实中间件链。
buffalo build 不自动触发 packr2,静态资源打包需手动介入
buffalo build 默认只处理 assets/(前端构建)和 templates/(plush 渲染),它不调 packr2,也不读 packr.New() ——除非你主动在代码里引入并生成 packrd.go。
- 安装
packr2正确命令是:go install github.com/gobuffalo/packr/v2/packr2@latest,不是buffalo plugins install(后者只认插件接口,不认工具二进制) - 要让
packr2生效,得在app.go或main.go里显式写packr.New("static", "./public"),再运行packr2生成packrd.go -
packrd.go必须提交进 Git,CI 构建时缺了它会 panic;而 Go 1.16+ 的//go:embed不需要中间文件,但无法热重载
真正容易被忽略的是:packr2 和 //go:embed 不能混用同一路径——它们是两套互斥的嵌入机制,选一个就到底,别交叉配置。










