Buffalo CLI安装失败主因是PATH未配置，需确认go env GOPATH非空并将其/bin加入PATH；修复方法为执行export PATH="$(go env GOPATH)/bin:$PATH"（Linux/macOS）或set PATH=%GOPATH%\bin;%PATH%（Windows），再新开终端运行buffalo version验证。
buffalo CLI 安装失败常见原因和修复方法
Buffalo CLI 必须通过 go install 或预编译二进制安装，不能用 npm install 或 go get（后者已弃用）。最常卡在「command not found」，根本原因是 PATH 没配对。
- 执行
go env GOPATH，确认输出非空（如/home/user/go）；若为空，先运行go mod init dummy触发 GOPATH 初始化 - 检查
$GOPATH/bin是否在系统 PATH 中：Linux/macOS 运行echo $PATH | grep "$(go env GOPATH)/bin"，Windows 用echo %PATH%手动搜索 - 若未包含，临时加进当前终端：
export PATH="$(go env GOPATH)/bin:$PATH"（Linux/macOS）或set PATH=%GOPATH%\bin;%PATH%（Windows） - 验证：新开终端，直接运行
buffalo version；输出类似v0.18.13即成功
buffalo new 项目时必须满足的前置条件
buffalo new 不是“随便在哪都能跑”的命令，它对当前目录和 Go 环境有硬性要求。跳过检查会导致生成失败或后续 buffalo dev panic。
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 必须在**空目录**下执行，否则报错
directory is not empty；即使目录里只有.git也不行 - 当前目录不能是已有 Go 模块的子目录（即不能有上层
go.mod），否则buffalo无法正确推导模块路径 - 若提示
no required module provides package github.com/gobuffalo/buffalo，说明本地 Go 版本 go1.26.0（2026 年稳定兼容版本） - 生成后立刻进项目目录，运行
go mod tidy补全子依赖；不执行这步，buffalo db migrate会因 pop/v6 缺失而 crash
buffalo dev 启动前必须手动完成的三件事
buffalo dev 不会自动帮你建库、跑迁移、装前端依赖——它只负责热重载。缺任何一环，服务要么启动失败，要么访问页面时直接 500。
- 先跑
go mod tidy和npm install（即使你打算删assets/，首次也得装，否则 Webpack 构建阶段报错退出） - 确认
database.yml中development配置有效（特别是dialect和database名），然后执行buffalo db create；若权限不足，需手动用 psql 或 mysql 创建库并授权 - 紧接着执行
buffalo db migrate；跳过这步，models.NewDB()连接后查users表会返回table not found
第一次启动 buffalo dev 后打不开 localhost:3000 怎么排查
终端显示 Starting application at http://127.0.0.1:3000 不代表服务真在监听。Buffalo 的端口逻辑容易被忽略：它会自动探测占用并换端口，但不会主动告诉你换了哪个。
- 仔细看终端最后一行输出——不是第一行，而是构建完成后的那条
Starting application at...，地址可能已是:3001或:4000 - 如果终端卡在
[0001] Building…不动，大概率是assets/下 Webpack 编译失败，检查node_modules是否完整、npm install是否真的跑完 - 执行
lsof -i :3000（macOS/Linux）或netstat -ano | findstr :3000（Windows）确认端口是否真被占；若被占，加参数buffalo dev -p 4000强制指定 - 浏览器打开时出现
connection refused，但终端无报错？检查main.go是否被误改——必须保留actions.App().Serve()调用，否则buffalo dev无法挂载 HTTP server
