必须先安装buffalo cli工具，否则buffalo new、buffalo dev等命令均报command not found；需go 1.21+，通过go install github.com/gobuffalo/cli/cmd/buffalo@latest安装或下载预编译包配置path，最后用buffalo version验证。
buffalo CLI 工具必须先装好，否则所有后续命令（如 buffalo new、buffalo dev）都会报 command not found。安装成功与否，只看新开终端能否执行 buffalo version 并输出类似 v0.18.13 的版本号。
确认 Go 环境是否达标
Buffalo 是用 Go 写的 CLI 工具，不兼容低版本 Go：
- 运行
go version，输出必须是go1.21或更高；低于此版本会触发go install编译失败 - 运行
go env GOPATH，确保返回非空路径（如/home/user/go），这是go install默认放二进制的位置 - 若未安装 Go，直接下载
go1.26.0（当前稳定兼容版）：前往 https://www.php.cn/link/81836b7cd16991abb7febfd7832927fd 安装，并配置好PATH
安装 buffalo CLI 的两种可靠方式
推荐优先用 go install，它自动编译、无需手动管理二进制文件：
- 执行
go install github.com/gobuffalo/cli/cmd/buffalo@latest - 该命令将二进制写入
$GOPATH/bin/buffalo，不是当前目录，也不是./bin - 若提示
cannot find module providing package，大概率是 Go 版本太低或网络无法访问 GitHub；此时改用预编译包
备用方案（无 Go 环境或网络受限时）：
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- Linux/macOS：去 GitHub Releases 下载
buffalo_*.tar.gz，解压后把buffalo文件复制到/usr/local/bin/，再运行chmod +x /usr/local/bin/buffalo - Windows：用 Scoop（推荐）——先
scoop bucket add extras，再scoop install buffalo；Scoop 会自动注册 PATH，省去手动配置
验证安装并初始化开发环境
这一步最容易被跳过，但却是新手卡住最多的地方：
- 关掉当前终端，新开一个——因为
$GOPATH/bin需要重新加载到 shell 的PATH - 执行
buffalo version；若输出版本号，说明 CLI 就绪 - 创建空目录，运行
buffalo new myapp（不要在已有 Go 模块里执行，否则会失败） - 进入项目目录，先跑
buffalo db migrate（否则buffalo dev启动后访问页面会 panic） - 最后执行
buffalo dev；默认监听:3000，若端口被占，加-p 4000换端口
常见启动失败原因和对应检查点
buffalo dev 启动后立即退出、白屏、500 错误，往往不是代码问题，而是环境没对齐：
- 数据库服务没开：PostgreSQL 要
systemctl start postgresql，MySQL 要systemctl start mysql，再用telnet localhost 5432测试连通性 - session 中间件未启用：检查
app.go是否有app.Use(session.Middleware())，缺了就无法读写 Session - config/session.yml 中
secure: true却在 HTTP 开发环境用：必须设为false，否则浏览器拒绝存 Cookie - config/database.yml 的
development区块字段填错（比如host写成localhost但 PostgreSQL 绑定的是127.0.0.1）
真正麻烦的从来不是命令输错，而是某个配置项在某个 YAML 文件里悄悄失效，又没有明确报错提示。
