Buffalo CLI在Linux安装失败90%是Go环境问题：需go1.21+、GOPATH有效且PATH包含$GOPATH/bin；推荐go install方式，预编译包需手动配置PATH及SQLite库。
Buffalo CLI 工具在 Linux 下安装失败，90% 是因为 go install 没跑通，或 $GOPATH/bin 没进 PATH——不是 Buffalo 本身的问题，而是 Go 环境链路断了。
确认 Go 版本和 GOPATH 是否就绪
Buffalo 是 Go 写的 CLI，不认低版本 Go，也不接受 GOPATH 模式（会直接让 buffalo new 报错）。必须满足两个硬条件：
-
go version输出至少是go1.21；低于此版本会触发cannot find module providing package -
go env GOPATH必须返回一个真实路径（如/home/you/go），不能是空或~/go这类未展开的写法 - 如果用的是 WSL2 或 Git Bash，务必检查是否手动设置了
GOPATH环境变量——Buffalo 强制要求 modules 模式，设了GOPATH就会静默降级，后续所有数据库命令（buffalo pop）全失效
用 go install 安装 buffalo CLI（推荐方式）
这是最干净、可复现的方式，不需要额外包管理器。执行前确保已连 GitHub（国内用户需配 GOPROXY）：
- 运行：
go install github.com/gobuffalo/cli/cmd/buffalo@latest - 二进制默认落到
$GOPATH/bin/buffalo，不是/usr/local/bin，也不是当前目录 - 安装完必须新开终端（或执行
source ~/.bashrc），再验证：buffalo version - 若仍报
command not found，立刻检查：echo $PATH | grep "$(go env GOPATH)/bin"——没输出就说明 PATH 没加对
预编译二进制包安装（无 Go 环境或网络受限时）
适用于没有 Go、或公司防火墙拦了 GitHub 的场景。注意：它绕过了 Go 编译，但运行时依赖没绕开：
- 去 GitHub Releases 下载对应架构的
buffalo_*.tar.gz（如buffalo_0.18.13_linux_amd64.tar.gz） - 解压后得到单个
buffalo二进制文件，复制到/usr/local/bin/或$HOME/bin（后者需确保该路径已在PATH中） - 赋执行权限：
chmod +x /usr/local/bin/buffalo - ⚠️ 即使用了预编译包，若项目启用 SQLite（
buffalo new --with-sqlite3），仍需系统有libsqlite3.so可被动态加载，否则buffalo dev启动时报undefined symbol: sqlite3_...
常见错误现象与定位点
别急着重装，先看这几条输出就能锁死问题环节：
-
command not found: buffalo→ 不是安装失败，是$GOPATH/bin或二进制所在目录没进PATH -
cannot find module providing package→ Go 版本太低，或GOPROXY没设导致拉不到模块索引 -
buffalo dev启动后立即 panic，堆栈含sqlite3→ 预编译包运行时缺系统级 SQLite 库，非 Buffalo 代码问题 -
buffalo new myapp生成项目但database.yml里 driver 是postgres而非预期的sqlite3→ 创建时没加--with-sqlite3参数，CLI 本身没毛病
真正卡住人的从来不是 buffalo 命令本身，而是 Go 环境变量、PATH 注册、SQLite 动态链接这三个隐性依赖。装完别急着建项目，先跑通 buffalo version 和 buffalo help，再动 new。否则后面查半天发现只是 ~/.bashrc 里少了一句 export PATH="$PATH:$(go env GOPATH)/bin"。
