如何安装Buffalo框架完成新项目创建步骤-Golang-PHP中文网

必须先装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。

如何安装buffalo框架完成新项目创建步骤

必须先装 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

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/