Buffalo 官方 CLI 从未提供 buffalo docker 命令,v0.18.0 起已彻底移除;Docker 化需手动编写 Dockerfile 和 docker-compose.yml,显式处理 public/、DB_URL、GO_ENV 及静态资源打包。

buffalo docker 命令不存在,别白找
Buffalo 官方 CLI 从 v0.18.0 起就移除了 buffalo docker 或 buffalo generate docker 这类命令。你执行 buffalo help 或查文档,根本找不到它——不是你漏装,是它压根没提供。
实际要做的三件事:手动建 Dockerfile、docker-compose.yml、调整启动逻辑
Buffalo 项目 Docker 化不是“一键生成”,而是按 Go 应用通用方式处理,核心是让二进制能跑起来、静态资源能加载、数据库能连上。常见错误是照搬 Node.js 项目的多阶段写法,结果 buffalo build 产出的二进制在容器里找不到 public/ 或 panic 在 packr2 加载阶段。
- 第一步:确保项目已成功运行过
buffalo dev,且public/目录非空(哪怕只放个.keep)——Docker 构建时会把它一起 COPY 进镜像 - 第二步:在项目根目录新建
Dockerfile,用多阶段构建,第一阶段用golang:1.21-alpine编译,第二阶段用alpine:latest运行,必须显式 COPY public/ 和 locales/ - 第三步:删掉
app.go里对plugins.Static()的调用(或注释掉),否则生产模式下会尝试从文件系统读public/,而 Alpine 镜像默认不带stat工具,直接 crash - 第四步:
buffalo build -o ./bin/app必须在宿主机执行(不能在 Dockerfile 里用go build),因为packr2需要读取本地public/和模板路径;编译完再 COPY 二进制进运行镜像
database.yml 不起作用,DB_URL 必须进容器环境
很多人把 config/database.yml COPY 进镜像就以为数据库配置好了,结果容器启动后报 dial tcp 127.0.0.1:5432: connect: connection refused。这是因为 Buffalo 运行时不读这个文件,models.NewDB() 只认 DB_URL 环境变量。
- 在
docker-compose.yml的 service 下必须写environment:块,显式注入DB_URL,例如postgres://postgres:pass@db:5432/myapp?sslmode=disable - 别写
env_file: .env—— Buffalo 默认不加载.env文件,除非你主动调用envy.Load(),而绝大多数模板没加这句 - PostgreSQL service 名必须和
DB_URL中 host 一致(如db),不能写localhost,Docker 内部 DNS 解析不到 -
GO_ENV=production也得设,否则buffalo build产物在容器里启动时仍走 development 模式逻辑,比如不压缩静态资源、不关闭 debug 日志
最容易被忽略的:public/ 和 assets/ 的双重角色
开发时 buffalo dev 同时跑 Go server(:3000)和 Webpack Dev Server(:3001),但生产镜像里这两者必须合并。如果你删了 assets/ 目录又没提前构建好 public/,或者 buffalo build 时没加 -v(verbose)看到 packr: finding assets 日志,上线后打开页面就是空白,Network 面板里全是 /assets/app.css 404。
- 确认
public/是由buffalo build自动生成的(不是你手动 mkdir 出来的),里面应有app.css、app.js、images/等 - 如果用了自定义前端构建(如 Vite),必须在
Dockerfile构建阶段先RUN npm ci && npm run build,再把dist/COPY 到public/覆盖原内容 - 运行容器前,用
docker run --rm -it your-app ls -la public/检查目录结构,确保不是空的


















