buffalo new 是 buffalo 唯一正确且不可跳过的初始化方式，必须在空目录下执行，生成全栈结构后依次运行 go mod tidy、buffalo db create、buffalo db migrate up，否则 buffalo dev 必然失败。

buffalo new 命令是 Buffalo 安装后唯一正确且不可跳过的初始化方式，它不是“创建空项目”，而是生成一个具备完整运行能力的全栈结构——跳过这步直接 buffalo dev 必然失败。

必须在空目录下执行 buffalo new

Buffalo 会拒绝在非空目录中初始化，报错类似 error: directory is not empty。这不是提示，是硬性限制。

• 先 mkdir myapp && cd myapp，再运行 buffalo new myapp
• 若已有 go.mod 或 main.go，删掉或换目录——Buffalo 不兼容已有 Go 模块的“叠加初始化”
• 命令默认生成带前端资产的全栈项目；如需纯 API，加 --api 参数：buffalo new myapp --api

buffalo new 后要立刻跑的三步命令

生成完只是文件落地，没做任何环境准备。以下顺序不能乱，缺一不可：

Buffalo框架 1.0.1

Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。

下载

• go mod tidy：拉取 buffalo、pop、plush 等依赖，写入 go.mod；若失败，大概率是 GOPROXY 不可用或网络问题
• buffalo db create：根据 models.NewDB() 中的配置（不是 database.yml！）尝试连接并建库；失败时检查 DB_URL 环境变量是否设对
• buffalo db migrate up：执行 models/migrations/ 下所有 SQL 迁移；若报 table does not exist，说明上一步 create 没成功，别硬跑 seed

为什么 buffalo dev 启动前必须确认 buffalo.dev.yml 存在

buffalo dev 默认依赖 buffalo.dev.yml 文件来决定监听行为和端口。该文件由 buffalo new 自动生成，但如果你删了或用 --api 初始化，它可能缺失。

• 缺失时 buffalo dev 会报错：failed to load dev config: open buffalo.dev.yml: no such file
• 手动补一个最简版即可：

  port: 3000
  watchers:
    - actions/
    - models/
    - templates/

• 注意：修改此文件后必须重启 buffalo dev，热重载不监听它的变更

真正容易被忽略的是：Buffalo 的数据库连接逻辑完全绕过 database.yml，它只读环境变量（如 DB_URL）或 models.NewDB() 里的硬编码。你改了 YAML 却没改 Go 代码，服务照样连不上——这个脱节点，90% 的新手会在第一次 buffalo dev 报 500 时卡住半天。