Buffalo CLI 命令围绕项目生命周期组织，非记忆式；必须在项目根目录运行，依赖数据库连接，无全局插件，new 需空目录+Go≥1.21+GOPATH/bin 在 PATH，db 命令仅建库/迁移不启连接池，resource 生成代码不可手动改名删模板，task 不自动初始化 DB，各命令环境相互隔离。
Buffalo 没有“完整命令教程”这回事——它的 CLI 命令不是靠记忆列表驱动的，而是围绕项目生命周期和 Cobra 主链组织的。硬背 buffalo g、buffalo db、buffalo task 所有子命令，不如盯住三个核心事实：
- 所有命令都必须在项目根目录下运行（
buffalo dev会 cd 到项目根，外部脚本不会） - 大部分命令依赖
app.Pop()或models.DB，没连上数据库就执行buffalo db migrate必 panic - 不存在全局插件、不扫描
$PATH、不读~/.buffalo/plugins，所谓“扩展”只能改项目内buffalo/cmd/
buffalo new 必须在空目录 + Go ≥1.21 + GOPATH/bin 在 PATH
这不是可选项，是启动器级限制。常见失败现象：command not found、directory is not empty、go install: no matching versions。
-
go version必须 ≥go1.21；低于此版本，go install github.com/gobuffalo/cli/cmd/buffalo@latest会静默失败或生成不可用二进制 -
go env GOPATH输出必须非空；若为空，先执行export GOPATH=$HOME/go（macOS/Linux 加到~/.zshrc），再确认$GOPATH/bin已加入$PATH -
buffalo new myapp只接受空目录；已有go.mod就报错退出，不能补救——得先go mod init myapp再重试 -
--api不是“轻量版”，是跳过assets/和 Webpack 构建逻辑；但若忘了删assets/，buffalo dev仍会尝试npm run build并卡在node_modules not found
buffalo db create/migrate 必须在 buffalo dev 前手动跑
buffalo db 不是服务组件，它只做两件事：建库、跑迁移文件。它不启动连接池、不初始化 models.DB、也不参与 HTTP 请求生命周期。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
-
buffalo db create创建数据库实例，但不会自动创建 schema；PostgreSQL 下需确保database.yml的dialect是小写"postgres"（写成postgresql会 silent fail） -
buffalo db migrate依赖models.NewDB()返回有效连接；如果DB_URL环境变量被覆盖（比如 CI 中设了DB_URL=sqlite://./test.db），database.yml配置完全无效 - 迁移失败时错误信息常藏在末尾：
no such table users不是表没建，是buffalo db migrate根本没跑成功；先检查终端最后一行是否输出up to version xxx - 想重置开发库？别手写 SQL 改
buffalo/cmd/root.go；直接buffalo db drop && buffalo db create && buffalo db migrate更安全
buffalo g resource 生成的代码不能手动改名或删模板
Buffalo 的路由绑定不是靠反射扫描方法名，而是靠 actions/app.go 中显式注册的 app.Resource("/users", &UsersResource{})，且内部硬编码匹配 List/Show 等方法名。
- 手动生成
actions/users.go后把List改成Index→ 访问/users直接 404，无任何提示 - 删掉
templates/users/目录 →buffalo dev不报错，但c.Render调用会 fallback 到空响应或 panic（取决于模板引擎配置） -
buffalo g resource users name:string会同时生成模型、迁移、控制器、模板路径、路由注册；漏掉任意一环（比如没运行迁移），buffalo routes里就看不到对应条目 - API 版本化不要写
app.Resource("/api/v1/users", &UsersResource{})；前缀会被 Buffalo 路由系统剥离，导致c.Param("id")解析失败；应统一用中间件拦截/api/v1/前缀
buffalo task 不是魔法，要手动确保 models.DB 初始化
buffalo task 本质是调用 tasks/tasks.go 里注册的函数，但它不自动加载应用上下文——没有 app 实例，也没有 buffalo dev 启动时隐式完成的 models.DB 初始化。
- 任务文件如
tasks/import_users.go必须在tasks/tasks.go中显式导入并注册：Task("import-users", ImportUsers) - 函数体内不能直接用
app.Pop()（因为没app）；得自己调models.DB，且要确保models.DB != nil；常见做法是在函数开头加if models.DB == nil { log.Fatal("DB not initialized") } - CSV 解析别用循环
Create；1000 行以上必慢；改用models.DB.CreateInBatches(users, 100)（需 Pop v6+） - Excel 导入必须用
qax-os/excelize；tealeg/xlsx对合并单元格支持差，且日期列读出来是float64，得转：time.Unix(0, int64(v)*1e7).UTC()
真正容易被忽略的点是：所有 CLI 命令的执行环境，和 buffalo dev 启动后的运行时环境，是隔离的。你在 buffalo dev 里能拿到的 app.Pop()，在 buffalo task 或 buffalo db migrate 里拿不到——它们各自初始化各自的连接。别指望一个地方配好就能处处生效。
