Buffalo CLI安装失败最常见的三个原因是：Go版本低于1.21、$GOPATH/bin未加入PATH、网络无法访问GitHub仓库；需分别验证go version、go env GOPATH及PATH配置，或改用预编译包。
buffalo CLI 安装失败最常见的三个原因
装不上 buffalo 命令，90% 是卡在这三处：Go 版本低于 1.21、$GOPATH/bin 没进 PATH、网络无法拉取 GitHub 仓库。
执行 go version，输出必须是 go1.21 或更高；低于这个版本，go install 会直接报错“unsupported Go version”。
运行 go env GOPATH 确认路径非空，然后检查 PATH 是否包含该路径下的 bin 目录——Linux/macOS 用户常漏掉 export PATH=$PATH:$GOPATH/bin 这步；Windows 用户用 Scoop 安装可绕过此问题。
- 若提示
cannot find module providing package，不是命令写错了，而是 Go 模块代理或网络问题，此时改用预编译包更可靠 - 不要在已有 Go 项目里执行
go install——它不依赖当前目录，跑错地方只会浪费时间 - 安装后必须新开终端验证，旧终端不会自动加载更新后的
PATH
第一次运行新项目必做的四条命令
进到空目录后，按顺序敲这四行，缺一不可：
buffalo new myapp → cd myapp → go mod tidy && npm install → buffalo db create && buffalo db migrate
buffalo new 必须在完全空白的目录下执行，否则报错退出；它生成的 go.mod 只声明顶层依赖，go mod tidy 才真正补全所有子依赖（比如 github.com/gobuffalo/pop/v6），跳过这步后续数据库操作大概率 panic。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
-
npm install即使你打算删掉assets/也得跑——buffalo dev启动时默认尝试调 Webpack，找不到node_modules就直接中止 -
buffalo db create依赖database.yml里的dialect和权限配置；PostgreSQL 用户若遇到permission denied，需先用psql -U postgres手动建库并GRANT -
buffalo db migrate严格按迁移文件名的时间戳升序执行；手动改过文件名会导致顺序错乱，数据库状态和代码不一致
buffalo dev 启不起来？先查这三个点
服务启动失败，八成不是代码问题，而是环境没对齐。
默认端口 :3000 被占用了？加 -p 4000 换个端口就行；但更常见的是数据库还没迁完就急着启动——buffalo dev 不会自动帮你跑迁移，表不存在时一查就 panic。
- SQLite 用户注意：
go build阶段需要系统级gcc编译驱动，macOS 上没装 Xcode Command Line Tools 会卡死 - 如果终端卡在 “Starting Buffalo…” 没反应，先
Ctrl+C中断，再运行buffalo task clear清缓存，否则旧错误可能被缓存住 - Windows 用户慎用 Git Bash——Buffalo 强制要求 modules 模式，一旦检测到
GOPATH模式，整个数据库命令链都会失效
自定义错误页为什么总不生效
写了 templates/error/404.plush.html 却还是看到白屏？不是语法错，是 Buffalo 根本没读到它。
错误页路径和命名是硬约定：templates/error/ 目录必须手动创建，文件名只能是 404.plush.html 或 500.plush.html，多一个下划线、少一个点、放错一级目录都不行。
Plush 模板里不能混用 html/template 语法（比如 {{.Data}}），必须写成 ，否则编译直接失败，但错误堆栈指向解析器而非你的文件行号，容易误判。
- 开发模式下修改错误页后必须重启
buffalo dev，它不会热重载templates/error/目录 - 确认
app.go里有app.Use(middleware.Renderer)，没这行中间件，所有模板（包括错误页）都会被忽略 - 用
--api创建的项目默认不带templates/，得先buffalo generate template error/404.html补上目录结构
