必须在空目录下执行buffalo new myapp，且需提前安装CLI、配置PATH、满足Go≥1.21；加--api会跳过前端构建支持，不推荐除非纯API需求。
Buffalo 框架新建项目必须用 buffalo new，不能用 go mod init 手动搭骨架 —— 否则缺 CLI 集成、asset pipeline 和 dev server 支持，后续跑不起来。
buffalo new 命令怎么执行才不出错
确保已按官方方式装好 buffalo CLI（即 go install github.com/gobuffalo/cli/cmd/buffalo@latest），且 $HOME/go/bin 在 $PATH 中。运行前先检查：
-
go version输出 ≥go1.21 -
which buffalo有返回路径，且buffalo version输出类似v0.18.10 - 当前目录不是已有 Go module（避免
go.mod冲突）
然后直接执行：buffalo new myapp。别加 --api，除非你确定永远不写 HTML 页面 —— 加了会跳过 webpack/ESBuild 配置，后期补前端要手动修一堆东西。
为什么 buffalo dev 启动后打不开 localhost:3000
常见原因不是代码问题，而是 asset 构建没触发或端口被占：
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 首次运行
buffalo dev会自动执行npm install和npm run build，若网络慢或 npm 镜像源不稳定，可能卡在 “building assets” 不报错但页面空白；可手动进myapp/assets目录跑npm run build看输出 - 默认端口
3000被占用时，buffalo dev不会自动换端口，也不会提示 —— 改用buffalo dev -p 4000换个端口试试 - Ubuntu 24.04 上偶发
libsqlite3.so或libssl.so找不到，此时装libsqlite3-0和libssl3即可
创建后删哪些文件能转成 API-only 服务
比直接用 --api 更可控：保留标准项目结构，再逐步移除前端依赖：
- 删掉
assets/目录（含package.json、webpack.config.js等） - 删掉
templates/和public/ - 修改
actions/app.go，注释或删掉env.IsDev()下的http.FileServer相关逻辑 - 把
actions/render.go里所有HTML方法删掉，只留JSON和XML处理
这样既保留 Buffalo 的路由、中间件、数据库集成能力，又避免了 --api 模式下缺失的构建钩子导致后续难扩展的问题。
真正容易被忽略的是：Buffalo 的 dev 模式依赖 fresh 监听文件变更，而它默认不监视 assets/ 外的任意目录 —— 如果你把配置文件或自定义中间件放在非标准路径，改了不会热重载，得手动重启 buffalo dev。
