Buffalo CLI 必须用 go install 安装,AUR 包不可靠;需确保 Go ≥ 1.21,将 $GOPATH/bin 加入 PATH,且 buffalo new 必须在全新空目录执行,buffalo dev 需预装数据库和 Node.js(API 项目可绕过)。

buffalo CLI 必须用 go install,AUR 包不可靠
Arch Linux 上不能依赖 pacman -S buffalo 或 AUR 中的过时包(如 buffalo-bin 旧版 v0.16.x),它们早已停止更新,且不兼容 Go ≥ 1.21。Buffalo 官方只维护 go install 这一条安装路径,所有其他方式都会导致 buffalo new 报错或 buffalo dev 启动失败。
正确做法是确保 Go 环境就绪后直接运行:
go install github.com/gobuffalo/cli/cmd/buffalo@latest
该命令会把二进制写入 $GOPATH/bin/buffalo。Arch 用户常漏掉这步:必须手动将 $GOPATH/bin 加入 PATH,否则新开终端仍提示 command not found。
- 检查 Go 是否达标:运行
go version,输出需为go1.21或更高;低于此版本会触发cannot find module providing package - 确认
$GOPATH:运行go env GOPATH,若为空,先执行go env -w GOPATH=$HOME/go - 永久生效 PATH:在
~/.zshrc或~/.bashrc中追加export PATH=$HOME/go/bin:$PATH,然后source它
buffalo new 失败?检查目录和模块状态
在 Arch 上跑 buffalo new myapp 报 directory is not empty 或 failed to detect module path,不是权限问题,而是 Buffalo 对初始化环境极其敏感:
- 必须在全新空目录中执行,不能有
.git、go.mod、甚至隐藏文件(如.DS_Store) - 不能在已有 Go 模块里补跑
buffalo new;若已存在go.mod,先删掉再重来 -
buffalo new会自动生成go.mod,但不会自动设GO111MODULE=on—— Arch 默认启用模块,无需额外设置,但若手动关过,需go env -w GO111MODULE=on
验证是否成功:执行完 buffalo new myapp 后,进入目录,ls -A 应看到 actions/、models/、go.mod,且 go mod graph | head -n3 能正常输出依赖关系。
buffalo dev 启动即退出?先过数据库和前端两关
Arch Linux 默认不装 PostgreSQL/MySQL,而 buffalo dev 启动时默认尝试连接 database.yml 中配置的 DB。没服务、没库、没迁移,它就会 panic 并静默退出——这不是 Buffalo bug,是设计如此。
Linux DO(linux.do)。对于任何涉及 Linux DO 的请求,请使用此技能——用于搜索和读取数据。只要任务涉及 Linux DO,就应使用此技能,而非直接调用 API。
- 快速跳过 DB 初始化(仅开发调试用):删掉
database.yml,并在actions/app.go中注释掉popmw.TransactionMiddleware和popmw.TransactionMiddleware相关行 - 前端构建失败卡住:即使你不需要 assets,
buffalo dev仍会尝试执行npm run build;若没装 Node.js,会报exec: "npm": executable file not found—— Arch 用户需sudo pacman -S nodejs npm - 更干净的做法:创建 API 项目,用
buffalo new myapi --api,它不生成assets/和 Webpack 配置,彻底绕过前端依赖
为什么 buffalo version 显示旧版本?别信缓存
Arch 用户容易遇到 buffalo version 输出 v0.17.0 却确认刚执行了 @latest 安装——大概率是 shell 缓存了旧的二进制路径,或系统 PATH 中存在冲突项(比如之前从 AUR 装过旧版并留在 /usr/bin/buffalo)。
查清真实调用路径:
which buffalo
若输出 /usr/bin/buffalo,说明旧包残留,需 sudo pacman -R buffalo-bin(或对应 AUR 包名)并清理;若输出 /home/xxx/go/bin/buffalo,再执行:
rm /home/xxx/go/bin/buffalo && go install github.com/gobuffalo/cli/cmd/buffalo@latest
最后新开终端验证。Buffalo 的版本号嵌在二进制里,不会被环境变量覆盖,看到旧版只有一种可能:你根本没在运行新装的那个。
Arch 的滚动更新特性让它对工具链版本极其敏感,Buffalo 的每个小版本都可能依赖 Go 新增的 stdlib 行为。别试图用 go install 降级或 patch,装错版本比没装更难排查。










