Buffalo CLI 安装需 Go ≥ 1.21 且 GOPATH 配置正确；推荐 go install 或预编译包安装；buffalo new 要求空目录，初始化后需执行 go mod tidy、buffalo db create/migrate，最后 buffalo dev 启动。
先确认 Go 环境是否达标
Buffalo CLI 是 Go 编写的，go version 必须 ≥ 1.21；低于这个版本，go install 会失败或生成不可用的二进制。运行 go env GOPATH 确保有输出——这是 go install 默认存放 buffalo 的路径，后续要加进 PATH。
用 go install 安装 buffalo CLI
在任意目录下执行：
go install github.com/gobuffalo/cli/cmd/buffalo@latest
它会编译并安装到 $GOPATH/bin/buffalo。如果报 cannot find module providing package，大概率是 Go 版本太低或 GitHub 访问受限，此时改用预编译包更稳。
- Linux/macOS：去 GitHub Releases 下载
buffalo_*.tar.gz，解压后把buffalo二进制丢进/usr/local/bin/并chmod +x - Windows：用 Scoop（
scoop bucket add extras && scoop install buffalo），自动注册 PATH
验证安装并初始化第一个项目
新开终端（确保 PATH 生效），运行：
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
buffalo version
看到类似 v0.18.13 的输出才算成功。接着在空目录下执行：
buffalo new myapp
注意：buffalo new 不能在已有 Go 模块或非空目录里跑，否则直接退出。它会自动生成完整项目结构、拉依赖、初始化数据库配置。
- 若只做 API 服务，加
--api参数跳过前端资产 - 生成后进入
myapp目录，先go mod tidy补全依赖，再buffalo db create && buffalo db migrate - 最后
buffalo dev启动——但别急着访问页面，没迁移数据库会 panic
常见卡点与绕过方式
最常卡在三处：
-
command not found：90% 是$GOPATH/bin没进 PATH，查echo $PATH，补上再新开终端 -
buffalo dev启动后页面 500：多半是buffalo db migrate漏了，或者数据库服务（Postgres/MySQL）根本没在运行 - 本地开发时
c.Session()返回nil：不是没配 session，而是热重载导致内存 store 被清空；换成 Redis store 或先关掉buffalo dev改用go run main.go排查
整个流程里，go install 和 buffalo new 都要求“干净环境”——没有残留的旧模块、没有同名目录、没有未启动的数据库，任何一步夹带状态都容易中断。
