必须先装CLI再初始化项目，中间不能跳步；Go版本需≥1.21，GOPATH/bin须加入PATH；buffalo new仅限空目录且无go.mod；全栈用buffalo new myapp，API服务加--api；首次运行前必执行go mod tidy、npm install、buffalo db create && migrate。
必须先装 CLI，再初始化项目，中间不能跳步——否则 buffalo new 会直接报错退出。
安装 buffalo CLI 工具前要确认 Go 环境
执行 go version，输出必须是 go1.21 或更高；低于这个版本，go install 会失败或生成不可用的二进制。运行 go env GOPATH 确认路径非空，因为 go install 默认把 buffalo 二进制放到 $GOPATH/bin 下——这个目录必须已加入系统 PATH，否则新开终端后仍提示 command not found。
常见错误现象：
-
go install github.com/gobuffalo/cli/cmd/buffalo@latest报cannot find module providing package：大概率是 Go 版本太低，或网络无法访问 GitHub（可临时设GOPROXY=https://goproxy.cn） -
buffalo version找不到命令：检查$GOPATH/bin是否在PATH中，macOS/Linux 用户可在~/.zshrc或~/.bash_profile里加export PATH=$GOPATH/bin:$PATH
执行 buffalo new 创建项目时的限制条件
buffalo new 只能在空目录下运行，且当前目录不能已有 go.mod。如果已有模块，必须先 go mod init myapp，再运行 buffalo new myapp，否则框架无法识别模块路径，后续所有命令都会出错。
使用场景差异：
- 全栈项目（带前端）：
buffalo new myapp—— 自动生成assets/、templates/、Webpack 配置等 - 纯 API 服务：
buffalo new myapp --api—— 跳过前端相关目录和构建逻辑，但依然生成models/和数据库配置占位
容易踩的坑：
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 误在已有代码的目录里跑
buffalo new，命令会立即退出并报directory is not empty - 用
--api创建后，忘了删掉assets/目录——导致buffalo dev启动时仍尝试调用npm run build，找不到node_modules就卡住
首次运行项目前必须补全三步依赖
刚 buffalo new 完成的项目，还不能直接 buffalo dev。必须按顺序执行：
-
go mod tidy：补全子依赖（如github.com/gobuffalo/pop/v6），否则buffalo db migrate会 panic -
npm install（或yarn install）：即使你打算删assets/，这步也不能跳——buffalo dev默认启动时会尝试编译前端资源，缺node_modules直接中断 -
buffalo db create && buffalo db migrate：先建库再迁移，跳过任一环节都会导致models.NewDB()连接后查表报table not found
注意 database.yml 文件只是示意，Buffalo 运行时不读它；真实连接由 models.NewDB() 决定，通常靠环境变量 DB_URL 或 APP_DATABASE_URL 驱动。
buffalo dev 启动失败的典型原因
最常见的两个失败点是：
-
buffalo dev报failed to connect to database：不是database.yml写错了，而是buffalo db create没执行，或数据库用户没权限创建表 -
buffalo dev卡在building assets...：说明npm install没成功，或assets/下的webpack.config.js被手动改坏，又或者用了--api却没删assets/
端口被占时别改源码——直接用 buffalo dev -p 4000 临时指定，或修改 buffalo.dev.yml；改完需重启命令才生效。
真正容易被忽略的是：所有这些步骤都强依赖顺序，go mod tidy 必须在 buffalo db migrate 前，npm install 必须在 buffalo dev 前，任何一步中断或跳过，后续就不是报错那么简单，而是整个服务根本起不来。
