必须先满足node.js≥v18.0、全局安装yarn、sqlite用户还需sqlite3命令行工具；buffalo new仅限空目录且无go.mod；首次运行buffalo dev前须执行go mod tidy、npm install（或yarn install）、buffalo db create && migrate。
buffalo new 命令必须满足哪些前置条件
直接运行 buffalo new myapp 大概率失败，不是命令不对，而是环境缺关键组件。Buffalo v0.22+ 强制要求 Node.js ≥ v18.0，且必须安装 yarn（不是 npm），否则卡在 assets 构建阶段，报错类似 yarn install failed。
- Node.js：用
node -v确认 ≥ 18.0；低于则升级，旧版（如 v16）会静默失败 - yarn：必须全局安装
yarn（npm install -g yarn），npm run build不被识别 - SQLite 用户额外注意：系统需有
sqlite3命令行工具（macOS 自带；Ubuntu/Debian 运行apt install sqlite3） - Go 环境本身要干净：
go mod tidy建议在buffalo dev前手动执行一次，避免依赖下载卡住
buffalo new 生成的项目结构里哪些文件可删、哪些不能动
生成后目录里看似标准，但很多文件对纯 API 或轻量服务是冗余的。真正不能删的是 actions/app.go（路由入口）、models/models.go（DB 初始化）、main.go（启动点）。其他如 templates/、assets/、public/ 可按需清空或移除，但别删整个目录——部分中间件（如 render.Middleware）仍会尝试读取 templates 路径，导致 panic。
-
templates/：若只做 JSON API，可留空，但不要删除目录；否则c.Render()调用会 panic 报template: "xxx" is undefined -
assets/和public/：前端资源目录，无 SSR 需求时可安全清空 -
config/database.yml：即使不用数据库也要保留，因为pop.Transaction中间件默认启用，删掉会导致启动报错 -
locales/：i18n 相关，未启用时可删，不影响启动
为什么 buffalo new --api 不能解决所有问题
buffalo new myapp --api 确实跳过了 templates/ 和前端构建，但它**没禁用中间件链**。你仍然会遇到：
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
-
session.Middleware尝试写 cookie，API 客户端不处理时会报http: named cookie not present -
csrf.Middleware对 POST/PUT/DELETE 强制校验 token，前端调用直接 403 -
pop.Transaction默认包裹每个 handler，哪怕你根本没定义 model，它也会尝试开启 DB 事务并 rollback -
app.JSON()返回时 Content-Type 仍是text/html; charset=utf-8，需手动设c.Set("Content-Type", "application/json")
所以 --api 只是“少生成”，不是“少加载”。真要轻量，得进 app.go 手动注释掉对应 app.Use(...) 行。
首次运行 buffalo dev 前最该检查的三件事
很多报错其实发生在启动前的隐式检查阶段，比如：
- 确认
GO111MODULE=on（现代 Go 默认开启，但某些旧 shell 配置可能关掉）；否则buffalo dev会提示no Go files in current directory - 检查
config/buffalo-app.toml里的dev_server_port是否被占用；默认 3000，冲突时不会自动换端口，而是卡住无响应 - 留意控制台第一行输出是否含
Starting Buffalo dev server...；如果停在Running yarn install...超过 90 秒，基本是网络问题——国内用户建议提前配好yarn config set registry https://registry.npmmirror.com
真正容易被忽略的是：Buffalo 的 CLI 和项目依赖完全解耦。重装 buffalo 二进制不会影响已有项目的 go.mod，但项目里误加的 github.com/gobuffalo/buffalo 模块反而会导致测试失败或中间件重复注册。
