Buffalo常用命令围绕“生成—迁移—启动—调试”四步闭环设计：buffalo new需GO111MODULE=on且可选--api；buffalo db migrate依赖schema_migrations表状态；buffalo dev默认监听3000端口但不报冲突；buffalo generate model与resource生成范围差异显著。
Buffalo 常用命令不是“背下来就能用”，而是围绕“生成—迁移—启动—调试”四步闭环设计的；不理解每个命令触发的底层动作，很容易在 buffalo dev 卡住或 buffalo db migrate 报错时无从下手。
buffalo new 项目名：必须确认 GOPATH 和模块初始化状态
执行 buffalo new 前，Go Modules 必须已启用（GO111MODULE=on），否则会因依赖解析失败而中断。它默认生成完整 MVC 结构，但如果你只需要 API 服务，应加 --api 标志跳过前端构建逻辑；否则后续 buffalo dev 会尝试启动 webpack 监听器，而你根本没装 Node.js。
常见错误现象：buffalo new myapp 后进入目录运行 buffalo dev 提示 webpack not found 或卡在 building assets...。
- 确保当前 shell 中
GO111MODULE为on（可运行go env GO111MODULE验证） - 若不需要前端资源，直接用
buffalo new myapp --api - 生成后检查根目录是否存在
go.mod；若缺失，手动运行go mod init myapp并补全依赖
buffalo db migrate：migration 表脏了比语法错更难排查
buffalo db migrate 不只是执行 SQL，它会先读取 models/migrations/ 下所有未标记为 applied 的文件，按时间戳升序执行，并在数据库中写入 schema_migrations 表记录。一旦某次 migration 执行中途 panic（比如 SQL 语法错、字段已存在），该记录可能已插入但变更未完成，导致表处于“半脏”状态——下次再跑就会报 duplicate key 或 column already exists，而非原始错误。
使用场景：本地开发频繁改模型时，建议每次重置环境都先清空迁移历史。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 用
buffalo db rollback -a回滚全部（慎用于生产） - 若只想清理状态不删数据，可手动连 DB 执行
DELETE FROM schema_migrations; - 检查 migration 文件命名是否含非法字符（如空格、中文），会导致解析失败且无明确提示
buffalo dev：端口冲突和热重载失效是两大静默陷阱
buffalo dev 默认监听 :3000，但它**不会报错提示端口被占**，而是直接 hang 住或秒退——这是最常被忽略的启动失败原因。热重载同样有隐性依赖：它靠 fsnotify 监听文件系统事件，但某些 IDE（如 VS Code 启用 atomic write）、Docker 挂载卷、或 WSL2 的 inotify 限制都会导致事件丢失。
参数差异：--skip-assets 可绕过 webpack 构建阶段，-p 4000 指定端口，--debug 开启详细日志（显示具体监听路径和文件变更事件）。
- 验证端口：启动前先运行
lsof -i :3000（macOS/Linux）或netstat -ano | findstr :3000（Windows） - 验证热重载：修改
actions/home.go后看终端是否打印restarting...；若无，用touch actions/home.go强制触发一次 - 若项目不含
assets/，务必加--skip-assets，否则 watcher 会反复尝试初始化不存在的构建链路
buffalo generate：model 和 resource 生成逻辑完全不同
buffalo generate model user name:string email:string 只创建 models/user.go 和 migration 文件，不碰路由或模板；而 buffalo generate resource users name:string email:string 会同时生成 model、migration、actions（CRUD 处理函数）、templates（HTML 页面）、以及自动注册到 app.Resource("/users", ...) 的路由。后者适合快速原型，但容易污染路由结构——比如你本想用 API 方式提供用户服务，却意外得到一堆 HTML 模板和重定向逻辑。
性能影响：resource 生成的模板默认带 Turbolinks 和 JS 表单提交逻辑，纯 JSON API 项目需手动删掉 templates/users/ 和相关 JS 引用，否则前端请求可能被中间件拦截或返回 406。
- API 项目只用
generate model+ 手动写 handler - 若已误用
generate resource，删掉templates/对应目录后，还需检查actions/app.go中是否残留app.Resource(...)调用 - 生成字段名别用 Go 关键字（如
type、range），否则models/user.go编译失败且错误指向不明
真正卡住人的从来不是命令记不住，而是 buffalo dev 不报错、buffalo db migrate 不回滚、buffalo generate 自动生成了你不想要的东西——这些行为背后都有明确的条件判断和路径依赖，盯住日志输出、确认当前目录结构、手动验证前置状态，比查文档更快定位问题。
