必须先安装Go 1.21+并清空GOPATH，再执行go install github.com/gobuffalo/cli/cmd/buffalo@latest安装Buffalo CLI；验证用buffalo version，失败则需将$GOBIN加入PATH；项目初始化须在空目录执行buffalo new，随后依次运行go mod tidy、npm install、buffalo db create && migrate、buffalo dev。
必须先装 Go 1.21+，再用 go install 安装 Buffalo CLI，不能靠包管理器或预编译二进制“一键运行”——否则 buffalo new 会因模块路径解析失败而报错。
安装前确认 Go 环境和系统约束
Buffalo 强制依赖 Go modules 模式，GOPATH 必须为空或未设置。Windows 用户若用 Git Bash 或 WSL2，需检查：echo $GOPATH 输出应为空；若非空，临时清空（如 unset GOPATH）再执行后续命令。
Linux/macOS 需预装 gcc 或 clang：这是为了编译 sqlite3 驱动，哪怕你不用 SQLite，buffalo new --with-sqlite3 或后续 buffalo db create 都可能卡在 go build 阶段。
- macOS：用
xcode-select --install装命令行工具 - Ubuntu/Debian：
sudo apt-get install build-essential - CentOS/RHEL：
sudo yum groupinstall "Development Tools"
用 go install 安装 buffalo CLI
别用 Homebrew/Scoop —— 它们装的是预编译二进制，虽能跑 buffalo version，但生成项目时可能因缺少 go 工具链支持而无法调用 go mod 或构建 assets。
执行：
go install github.com/gobuffalo/cli/cmd/buffalo@latest
验证是否成功：
buffalo version 应输出类似 v1.0.1 的版本号；若提示 command not found，说明 $GOBIN（默认为 $GOPATH/bin）未加入 $PATH，需手动添加。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
初始化并运行第一个项目
Buffalo 不允许在非空目录下执行 buffalo new，也**不接受已有 go.mod 的目录**——它会拒绝生成，除非你先 go mod init myapp 并确保模块名与项目名一致。
步骤如下：
- 新建空目录：
mkdir myapp && cd myapp - 生成项目：
buffalo new myapp（若跳过前端，加--api） - 拉依赖：
go mod tidy && npm install（npm install不能省，buffalo dev启动时会尝试构建 Webpack） - 建库并迁移：
buffalo db create && buffalo db migrate（注意顺序，create必须在migrate前） - 启动服务：
buffalo dev（默认端口:3000，被占时用buffalo dev -p 4000）
访问 http://localhost:3000，看到 Buffalo 默认首页即成功。
常见失败点和绕过方式
如果 buffalo dev 启动后立即 panic 并报 table users does not exist，不是代码问题，而是 buffalo db migrate 没执行，或执行时没连上 database.yml 中配置的数据库（比如 PostgreSQL 用户权限不足、host 写成 127.0.0.1 但 pg_hba.conf 只允许 localhost）。
如果 buffalo db create 报 permission denied，说明当前数据库用户无建库权限，需用 postgres 账户手动执行：createdb myapp_development，再重试。
SQLite 用户若遇到 undefined reference to sqlite3_*，是系统缺 libsqlite3-dev（Debian/Ubuntu）或 sqlite3-devel（RHEL/CentOS），装完再 go mod tidy 一次。
真正容易被忽略的是：database.yml 文件只是给人看的，Buffalo 运行时不读它；实际连接由 models.NewDB() 决定，它优先读环境变量 DB_URL。所以改了 database.yml 却没生效，八成是忘了设 export DB_URL=... 或没写进 .env。
