buffalo安装后需依次执行buffalo new、go mod tidy、npm install、buffalo db create/migrate，最后buffalo dev启动；若跳过任一环节或path、go_env、database.yml配置错误，将panic退出。
Buffalo 安装完成后不能直接运行，必须先初始化项目、安装依赖、建库迁移，否则 buffalo dev 会 panic 退出。
确认 Buffalo CLI 已正确安装
运行 buffalo version，输出应包含类似 v0.18.0 或更高版本号。若提示命令未找到，说明 go install 后未将 $GOPATH/bin 加入系统 PATH；若版本低于 v0.18.0，热加载功能不可用，需重新执行：
go install github.com/gobuffalo/cli/v2@latest
注意：不是 github.com/gobuffalo/cli/cmd/buffalo（旧路径已弃用）。
新建项目并完成三步初始化
Buffalo 不支持在空目录外直接运行，也不接受已有代码的“接入式”启动。必须从 buffalo new 开始：
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 在空目录下执行
buffalo new myapp（或加--api跳过前端） - 进入项目后立刻执行
go mod tidy—— 缺这步会导致后续buffalo db migrate因 pop/v6 依赖缺失而 panic - 紧接着运行
npm install（即使删了assets/，首次也必须装，否则buffalo dev启动时因找不到node_modules直接中止） - 再执行
buffalo db create和buffalo db migrate——buffalo dev不自动做迁移，访问页面时才触发 DB 查询，此时表不存在就会 crash
启动服务前检查两个关键文件
buffalo dev 启动失败最常见的原因是缺失以下任一条件：
- 项目根目录下没有
buffalo.dev.yml，且main.go中未调用app.Serve()（新版本生成的项目默认有，但手动修改过main.go可能误删） -
database.yml中的占位符如无法被解析 —— Buffalo 只加载以APP_为前缀的环境变量，DBPASSWORD不会被读取，应改用APP_DATABASE_PASSWORD并在database.yml中写成
启动后终端会输出实际监听地址（如 Starting application at http://127.0.0.1:3001），端口可能因冲突自增，别只认默认的 :3000。
热加载不生效？先验证监听是否触发
修改任意一个 actions/home.go 文件（比如末尾加一行 // test），保存后观察终端是否立即打印 [0001] Building…。没反应说明监听失效，常见原因：
-
buffalo.dev.yml缩进错误：YAML 必须用两个空格，tab 或 3 个空格都会导致配置被忽略，退回到默认行为 - 自定义了
--watch-dir但路径写错，或遗漏了templates/导致改 HTML 模板不重启 - 编辑器启用“安全写入”（如 VS Code 的
files.useExperimentalFileWatcher），会先写临时文件再原子替换，Buffalo 默认监听机制可能错过事件；可临时关闭该选项或改用inotifywait类工具验证底层文件变更是否真实发生
真正卡住的地方往往不在命令本身，而在环境变量注入时机、YAML 格式细节、或编辑器与文件监视器之间的隐式协作——这些点不报错，但会让整个流程静默失败。
