buffalo new 必须在完全空目录下执行，go 版本严格限定为 1.23 或 1.24；全栈与 api 项目不可混用或降级；初始化后须依次执行 go mod tidy、npm install（全栈）、buffalo db create、buffalo db migrate 四步，缺一不可。
buffalo new 必须在空目录下执行，否则直接报错退出
这是最常卡住新手的第一步。buffalo new 不会清空当前目录，也不会跳过已有文件——它只认“完全空白”。哪怕目录里只有一个 .git 或 README.md，命令都会立即失败并输出类似 error: directory is not empty 的提示。
实操建议：
- 用
mkdir myapp && cd myapp新建并进入目录，别复用旧项目夹 - 执行
ls -a确认无隐藏文件（尤其注意.git、.env） - Windows 用户请勿在资源管理器中手动新建“新建文本文档.txt”再改名——可能残留 NTFS 元数据，导致 buffalo new 拒绝识别为空目录
Go 版本必须是 1.23 或 1.24，低于或高于都不行
Buffalo 当前（2026年10月）不兼容 Go 1.21/1.22，也不支持 1.25+。运行 go version 输出必须是 go version go1.23.5 或 go version go1.24.1 这类格式。用 1.26.0 会触发 panic；用 1.22 会导致 go install 编译出的 buffalo 二进制无法启动。
常见错误现象：
-
buffalo new报panic: interface conversion: interface {} is nil→ 极大概率是 Go 版本不对 -
go install github.com/gobuffalo/cli/cmd/buffalo@latest后buffalo version无响应 → 检查 Go 是否为 1.23/1.24 - Mac 用户用 Homebrew 装的 Go 常是 LTS 版（如 1.21），需手动下载安装包覆盖
全栈项目与 API 项目生成命令参数不能混用
buffalo new myapp 和 buffalo new myapp --api 生成的项目结构差异极大，中间不能补救。前者带前端构建链、Plush 模板、Webpack 配置；后者删掉所有 assets 相关逻辑，禁用模板渲染，只留 JSON 接口骨架。
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
关键区别：
- --api 项目默认不生成
assets/目录，buffalo dev启动后不会监听 Webpack 编译事件 - --api 项目里
app.Use(plugins.Static())默认被注释，若手动开启会导致buffalo build卡死 - 想从全栈项目“降级”为 API 项目？不行。只能删掉整个目录，重新用
--api初始化
初始化后必须立刻执行四步，缺一不可
buffalo new 只是生成代码骨架，真正让项目跑起来要靠后续四条命令按顺序执行。跳过任意一步，buffalo dev 都会在启动阶段 panic 或返回 500。
这四步是：
-
go mod tidy—— 拉取所有 Go 依赖，修复go.sum不一致问题 -
npm install（仅全栈项目）—— 安装前端依赖，否则buffalo dev会报webpack not found -
buffalo db create—— 创建数据库（PostgreSQL/MySQL/SQLite），不是建表 -
buffalo db migrate—— 执行迁移脚本建表，即使不用 DB 也得跑，否则 pop 初始化失败
最容易被忽略的是最后一步：很多人以为没配数据库就跳过 buffalo db migrate，结果 buffalo dev 启动后访问任何页面都 panic，错误日志里反复出现 connection is nil。
