必须先安装buffalo CLI，再配置数据库和会话，否则buffalo new、buffalo dev等命令无法运行；需确保Go≥1.21、$GOPATH/bin加入PATH，执行go install github.com/gobuffalo/cli/cmd/buffalo@latest并用buffalo version验证。

必须先装好 buffalo CLI，再配置数据库和会话，否则 buffalo new、buffalo dev 等命令根本跑不起来——这是新手卡住的第一道墙。

安装 buffalo CLI 命令行工具

Buffalo 是 Go 写的 CLI 工具，不依赖项目目录，但强依赖 Go 环境。

• 先确认 Go 版本：运行 go version，输出必须是 go1.21 或更高；低于此版本会触发 go install 编译失败
• 确保 go env GOPATH 有输出，且该路径下的 bin/ 目录已加入系统 PATH（Windows 用户注意检查是否重启终端）
• 执行安装命令：go install github.com/gobuffalo/cli/cmd/buffalo@latest —— 它会把二进制文件放到 $GOPATH/bin/buffalo
• 若提示 cannot find module providing package，大概率是网络问题或 Go 版本太低，此时改用预编译包：去 GitHub Releases 下载对应系统的 buffalo_*.tar.gz，解压后把 buffalo 文件放进 /usr/local/bin（macOS/Linux）或加进 Windows PATH

验证：新开终端，运行 buffalo version。输出类似 v0.18.13 才算成功；如果报 command not found，90% 是 $GOPATH/bin 没进 PATH。

配置 database.yml 开发数据库连接

这个文件只是给人看的参考，Buffalo 运行时不读它——但它直接影响 buffalo pop create -a 和 buffalo db migrate 是否能连上数据库。

Buffalo框架 1.0.1

Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。

下载

• 先确认数据库服务真在跑：PostgreSQL 就 pg_ctl status 或 systemctl status postgresql；MySQL 就 mysqladmin ping -u root -p；再用 telnet localhost 5432 测试端口通不通
• 编辑 config/database.yml 中的 development: 区块，关键字段不能错：
  • dialect 必须小写且拼写准确：PostgreSQL 用 "postgres"（不是 postgresql 或 pg），MySQL 用 "mysql"
  • PostgreSQL 的 host 写 "localhost"，MySQL 的 host 建议写 "127.0.0.1"（避免 Unix socket 解析失败）
  • 密码、端口、库名要跟真实实例一致；database 字段填的是你要创建的库名，不是现有库
• 执行 buffalo pop create -a 创建库；失败时错误信息里带 dial tcp 就说明 host/port/user/password 至少有一项不对，别猜，逐项核对

启用 session 并避免 c.Session() 返回 nil

默认生成的项目不自动启用 session 中间件，c.Session() 会一直返回 nil，而且没任何提示。

• 打开 app.go，找到 app.Use(...) 调用链，在所有路由注册（比如 app.GET）之前，插入一行：app.Use(session.Middleware())
• 如果你用 Redis 存 session（推荐），得手动换 store：go get github.com/gobuffalo/buffalo-session/redis，然后在 app.go 里初始化：store := redis.NewStore("localhost:6379", "", "", "")，再传给中间件：app.Use(session.Middleware(store))
• 每次写 session 都必须显式调用 c.Session().Save()，否则浏览器收不到 Set-Cookie 头——这一步漏掉，刷新页面就丢数据
• 开发时 config/session.yml 中的 secure 应设为 false（否则本地 http://localhost:3000 无法写入 Cookie）；secret 必须是非空字符串，否则 Save() 会 panic

第一次运行项目前必须做的三件事

顺序不能乱，缺一不可：依赖没拉全、数据库没建好、服务没启起来，buffalo dev 会直接退出，且错误堆栈藏得很深。

• 进项目根目录，先跑 go mod tidy 补全所有 Go 依赖（包括 pop/v6、plush）；再跑 npm install（哪怕你不用前端，Webpack 编译步骤也会被触发）
• 确保 database.yml 配置正确后，执行 buffalo db create → buffalo db migrate；跳过迁移会导致查询表时报 table not found
• 最后运行 buffalo dev；它默认监听 :3000，如果端口被占，CLI 会自动换一个并打印出来——务必看终端最后一行的实际地址，别凭记忆访问 localhost:3000

热重载只监听标准目录（actions/、models/、templates/），如果你把代码拆到 ui/ 或 lib/，得用 --watch-dir 显式声明，否则改了也不触发重建。