buffalo new 是唯一正确入口,必须在空目录下执行;需确保 GOPATH 为空、Go≥1.21、目录名仅含小写字母数字和连字符,且无任何文件(含隐藏文件),否则直接失败。

buffalo new是唯一正确入口,必须在空目录下执行,否则直接失败。
执行 buffalo new 前必须清空环境
Buffalo 对 Go 环境极其敏感,不是“装了就能用”:
-
GOPATH必须未设置或为空——echo $GOPATH应无输出,否则buffalo new会误入 GOPATH 模式导致 module 名解析错乱 - Go 版本需 ≥1.21,且启用 modules(默认已开启);用
go version和go env GO111MODULE双重确认 - 当前目录不能有
go.mod、node_modules、assets/或任何文件——它连隐藏文件(如.git)都拒绝容忍 - 目录名只能含小写字母、数字和连字符(
-),不能有.、_或大写,否则生成的 module 名非法,后续go build报错
buffalo new 的参数决定项目骨架形态
不加参数是全栈默认,但多数场景需要明确裁剪:
- 纯 API 服务:
buffalo new myapi --api—— 跳过前端构建、模板引擎和静态资源打包逻辑 - 要 React/Vue 支持:
buffalo new myapp --with-nodejs—— 生成assets/和package.json,但不会自动装依赖,得手动npm install - 不用 Pop ORM:
buffalo new myapp --skip-pop—— 不生成models/、database.yml和迁移命令 - 指定数据库:
buffalo new myapp --db-type postgres(可选postgres/mysql/sqlite3)—— 影响database.yml初始配置和驱动导入
初始化后必须立即跑的三步,缺一不可
buffalo new 只生成代码,不拉依赖、不建库、不启动服务。跳过任一环节,buffalo dev 必然失败:
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
-
go mod tidy—— 下载 Go 依赖并写入go.mod;若失败,大概率是 module 名与目录名不一致(比如目录叫my-app但go.mod写了module my_app) -
npm install(即使--api也要跑)—— Buffalo CLI 在buffalo dev中会尝试触发 Webpack 构建,没node_modules就卡住 -
buffalo db create && buffalo db migrate up—— 先建库再建表;若用--skip-pop或--api且没配database.yml,这步可跳过,但得确认app.go里没调pop.Connect
buffalo dev 启动失败的常见信号
它不是“启动即成功”,终端最后一行必须出现 Starting application at http://... 才算真正就绪:
- 卡在
Building...不动 → 大概率models.go里Pop()初始化失败(比如database.yml中dialect拼错成postgresq) - 报
command not found→buffaloCLI 未正确安装,或$GOBIN(默认$GOPATH/bin)未加入$PATH - CSS/JS 404 → 没用
buffalo dev启动,而是go run main.go;Buffalo 的静态资源路由由 CLI 控制,原生 Go HTTP 无法识别 - 端口被占时 CLI 会自动递增(:3000 → :3001 → :3002…),但不会提示最终端口——务必盯紧终端最后一行地址,别硬刷
localhost:3000
真正容易被忽略的是:buffalo new 生成的 module 名直接取自当前目录名,且写死进 go.mod 第一行。一旦目录名违法(比如含点),整个项目就废了,改 go.mod 后还得同步所有 import 引用,比重开一个目录还麻烦。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










