Buffalo 开发环境需先安装 Go 1.21+ 和 buffalo CLI,配置 GOPATH 并将 $GOPATH/bin 加入 PATH;新建项目后依次执行 go mod tidy、npm install、buffalo pop create -a、buffalo db migrate,最后运行 buffalo dev。

Buffalo CLI 必须先装好,否则 buffalo new、buffalo dev 全部报 command not found;Go 环境低于 1.21 就会编译失败,别硬试。
确认 Go 环境并安装 buffalo CLI
执行 go version,输出必须是 go1.21 或更高——低于这个版本,go install github.com/gobuffalo/cli/cmd/buffalo@latest 会卡在 “cannot find module” 错误里。别用旧版 Go 凑合,直接去 go.dev/dl/ 下 go1.26.0 安装包。
go env GOPATH 要有输出(比如 /home/user/go),这是 go install 默认放二进制的位置。如果没设,先运行 go env -w GOPATH=/path/to/your/go。
然后跑这行命令:
go install github.com/gobuffalo/cli/cmd/buffalo@latest
装完新开终端,执行 buffalo version。如果提示 command not found,说明 $GOPATH/bin 没进 PATH——Linux/macOS 加到 ~/.bashrc 或 ~/.zshrc 末尾:export PATH="$GOPATH/bin:$PATH";Windows 用户检查系统环境变量是否包含该路径。
初始化项目并拉齐依赖
选一个空目录,运行 buffalo new myapp。它不会覆盖已有文件,但目录不能含 go.mod 或 buffalo 相关结构,否则直接退出。
进项目根目录后,立刻执行:
-
go mod tidy:补全所有子依赖,比如github.com/gobuffalo/pop/v6和github.com/gobuffalo/plush,缺了它们后续buffalo db migrate会 panic -
npm install(或yarn install):即使你打算删掉assets/,也得先装,因为buffalo dev启动时默认调 Webpack 编译器,找不到node_modules就中断
这两步顺序不能颠倒,go mod tidy 必须在 npm install 前完成——否则某些前端构建脚本可能依赖 Go 工具链生成的配置。
Buffalo框架 1.0.1 版本源码包下载,适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
配置 database.yml 并建库
打开 config/database.yml,只改 development: 区块。PostgreSQL 用户注意三点:
-
dialect必须写"postgres"(小写,拼成postgresql或pg都会报 “unknown dialect”) -
host写"localhost",别写"127.0.0.1"(macOS 上可能走 Unix socket 导致连接失败) - 确保本地 PostgreSQL 正在运行:
pg_ctl status或systemctl is-active postgresql,端口 5432 必须可连(telnet localhost 5432)
MySQL 用户把 host 改成 "127.0.0.1",加 sslmode: "false" 和 parseTime: "true",否则驱动初始化失败。
配置完运行:
buffalo pop create -a
看到 created database myapp_development 才算成功。如果报 failed to connect to `host=localhost user=postgres database=`,就回头核对 user、password、port——别猜,逐项 psql -U postgres -h localhost -p 5432 手动连一次。
启动服务前必须跑迁移
buffalo dev 不会自动执行迁移,它只管编译和热重载。不跑 buffalo db migrate 就启动,第一次访问页面就会 panic:table users does not exist(哪怕你还没建任何 model)。
所以固定三步顺序:
-
buffalo db create(等价于pop create -a,创建空库) -
buffalo db migrate(应用migrations/下所有未执行的 SQL 文件) -
buffalo dev(此时服务才能正常查表、渲染模板)
迁移文件名里的时间戳不能手动改,否则顺序错乱会导致数据库状态和代码模型不一致——这是线上事故高发点,不是开发时的小问题。
database.yml 里写的密码、host、port,和你本地数据库实际运行参数,必须一字不差;go mod tidy 和 npm install 的执行顺序,以及 buffalo db migrate 必须在 buffalo dev 之前,这些地方一旦出错,错误信息往往藏在深层 panic 里,而不是直接告诉你哪一行配错了。

















