必须先安装buffalo CLI并确保Go版本≥1.21，再执行buffalo new生成项目；需在空目录中运行、补全go.mod、执行go mod tidy和npm install，并正确配置database.yml及完成buffalo db create与migrate，否则buffalo dev将失败。
必须先装好 buffalo CLI，再用 buffalo new 生成项目；跳过 CLI 安装或漏掉 Go 模块初始化，buffalo new 会直接失败。
安装 buffalo CLI 前必须确认 Go 环境
执行 go version，输出必须是 go1.21 或更高版本。低于此版本会导致 go install 编译失败。如果没装 Go，去 https://www.php.cn/link/81836b7cd16991abb7febfd7832927fd 下载 go1.26.0 并配置好 PATH。
运行 go env GOPATH，确保有非空输出——这是 go install 默认存放 buffalo 二进制的位置。若未加入系统 PATH，后续所有命令都会报 command not found。
- 在终端中运行：
go install github.com/gobuffalo/cli/cmd/buffalo@latest - 关掉当前终端，新开一个，运行
buffalo version验证。输出类似v0.18.13即成功 - 若提示
cannot find module providing package，说明网络无法访问 GitHub 或 Go 版本太低，改用预编译包：去 GitHub Releases 下载对应系统的buffalo_*.tar.gz，解压后把buffalo文件复制到/usr/local/bin/（Linux/macOS）或%LOCALAPPDATA%\Scoop\shims\（Windows + Scoop）
buffalo new 生成项目时的硬性前提
buffalo new myapp 不是“随便在哪都能跑”的命令。它要求当前目录为空，且项目名不能与已有 Go 模块名冲突。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 进入一个全新空目录，比如
mkdir ~/myproject && cd ~/myproject - 运行
buffalo new myapp。它会自动创建go.mod、拉取依赖、生成actions/、models/、templates/等标准结构 - 若提示
no go.mod found或模块路径错误，手动补上：go mod init myapp（模块名必须和项目名一致），再重试buffalo new myapp - 加
--api参数可跳过前端资产（assets/、templates/），适合纯后端服务
第一次运行前必须补全三步，缺一不可
生成完项目只是开始。buffalo dev 启动前，必须完成依赖安装、数据库初始化、迁移执行——否则服务要么 panic，要么页面报 table not found。
- 进入项目根目录，运行
go mod tidy补全所有 Go 子依赖（go.mod只声明顶层依赖，不拉取 pop/v6 等实际需要的包） - 运行
npm install（即使你删了assets/）。因为buffalo dev默认尝试构建 Webpack，找不到node_modules会直接退出 - 编辑
config/database.yml中的development区块，填对dialect（如"postgres"，不能写成postgresql）、host、port、user、password；然后执行buffalo db create和buffalo db migrate
启动服务并验证是否真跑起来了
buffalo dev 默认监听 :3000，但它不会静默失败——出问题时会立刻打印错误并退出。不要只看终端有没有“Starting…”就以为成功了。
- 运行
buffalo dev，观察终端输出。如果看到Starting application at http://127.0.0.1:3000，再打开浏览器访问该地址 - 如果卡在
Building…不动，大概率是node_modules缺失或database.yml连接参数错（比如 PostgreSQL 没开服务、端口不通） - 如果浏览器返回 500 或空白页，检查终端是否有
panic: table users does not exist类错误——说明buffalo db migrate没执行，或 migration 文件没被识别（文件名必须是时间戳开头，如20240101120000_create_users.up.sql） - 端口被占时，CLI 会尝试下一个可用端口并明确提示，务必留意终端最后一行的实际地址，别默认只刷
:3000
最常被忽略的是 database.yml 的 dialect 拼写和 PostgreSQL/MySQL 服务本身是否真的在运行——Buffalo 从不帮你启数据库，它只负责连接。另外，go mod tidy 和 npm install 是两个独立动作，少任何一个，buffalo dev 都会在不同阶段崩溃，而不是统一报错。
