Buffalo CLI 安装失败90%因Go版本＜1.21或PATH未包含$GOPATH/bin；go install报“cannot find module”即版本过低或网络不通，buffalo version提示command not found说明二进制未被shell识别。
Buffalo CLI 安装失败，90% 是 Go 环境或 PATH 没对齐，不是 Buffalo 本身有问题。
go install 报 “cannot find module providing package”
这不是 Buffalo 的 bug，而是 Go 工具链拒绝执行安装的明确信号：
- Go 版本低于
1.21：运行go version，输出必须是go1.21.x或更高；低于此版本会直接触发该错误 - 网络无法访问 GitHub：国内常见，
go install默认走 github.com，没代理就拉不到源码 - 没配置
GOPROXY：临时修复可加这句再试：go env -w GOPROXY=https://proxy.golang.org,direct
别硬扛——换预编译包更稳。
buffalo version 提示 command not found
说明二进制文件生成了，但 shell 找不到它。关键检查点：
- 执行
go env GOPATH，确认返回非空路径（如/home/user/go） - 二进制实际在
$GOPATH/bin/buffalo，不是当前目录，也不是./bin - 必须新开终端——旧终端的
PATH没包含$GOPATH/bin，改完PATH也不生效 - macOS/Linux 用户若用 zsh，请检查
~/.zshrc是否有export PATH="$GOPATH/bin:$PATH"
Windows 用户用 Scoop 安装则基本绕过这个坑，scoop install buffalo 自动注册 PATH。
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
Linux/macOS 下载预编译包后仍 command not found
解压出的 buffalo 文件只是普通可执行文件，没放进 PATH 就等于没装：
- 别放在项目目录或桌面——放
/usr/local/bin/（需sudo）或$HOME/bin/（需确保该路径已入PATH） - 赋执行权限必不可少：
chmod +x /usr/local/bin/buffalo - 验证位置是否生效：
which buffalo应输出路径；ls -l $(which buffalo)应显示-rwxr-xr-x
常见误操作：把 buffalo 放进 /tmp 或当前目录，然后只运行 ./buffalo version ——这不算“安装成功”，后续 buffalo new 还是会报错。
buffalo new 启动就 panic 或报 database error
这不是 CLI 安装问题，而是新手常混淆的“安装完成”和“环境就绪”：
-
buffalo version成功 ≠ 项目能跑；buffalo new myapp后必须进目录执行buffalo db migrate，否则首次buffalo dev访问页面就会 panic - panic 常见源头是
config/database.yml配置错：比如dialect: "postgresql"（错）→ 正确是"postgres"；或host: "localhost"但 PostgreSQL 实际监听127.0.0.1 - PostgreSQL 服务根本没开也会导致同样现象：先
systemctl start postgresql（Linux）或打开 pgAdmin（macOS/Windows），再测试psql -U postgres -d postgres
真正卡住人的，从来不是“怎么装”，而是“装完下一步该查什么”。PATH、Go 版本、数据库连通性——这三个点漏掉任意一个，都会让 buffalo new 看似成功，实则埋雷。
