heroku/builder

Heroku Cloud Native Buildpack Builder 镜像文档

镜像概述和主要用途

Heroku Cloud Native Buildpack Builder（以下简称"Heroku CNB Builder"）是基于 Cloud Native Buildpacks（CNB）规范的预配置构建环境镜像。该镜像集成了 Heroku 官方维护的 Buildpack 集合，旨在提供标准化、自动化的应用构建流程，帮助开发者将源代码快速构建为 OCI 兼容的容器镜像，无需手动编写 Dockerfile。其核心用途是简化容器化构建流程，降低多语言应用的容器化门槛，同时确保构建产物符合行业标准。

核心功能和特性

符合 Cloud Native Buildpacks 规范

严格遵循 CNB v3 及以上规范，兼容 OCI 镜像标准，支持与 pack CLI、Tekton、GitHub Actions 等主流 CNB 工具链集成。

多语言构建支持

内置 Heroku 官方 Buildpacks，覆盖主流开发语言和框架，包括但不限于：

• Node.js（含 npm/yarn/pnpm 支持）
• Python（含 pip/Poetry 依赖管理）
• Java（Maven/Gradle 构建支持）
• Ruby、PHP、Go、.NET 等

自动化构建流程

• 自动检测应用类型（通过 Buildpack 探测器识别源代码特征）
• 自动化依赖安装（如 npm install、pip install、mvn package 等）
• 运行环境配置（设置环境变量、启动命令、健康检查等）
• 产物优化（清理构建缓存、最小化运行时镜像体积）

可定制扩展能力

• 支持通过 --buildpack 参数添加自定义 Buildpacks（本地路径或 Git 仓库）
• 允许覆盖默认 Buildpack 优先级，灵活调整构建逻辑
• 支持构建缓存（通过 pack 的缓存卷机制加速重复构建）

与 Heroku 生态集成

兼容 Heroku 应用配置模型，可直接复用 Heroku 应用的环境变量、构建配置（如 Procfile、app.json）等，降低跨环境迁移成本。

使用场景和适用范围

快速原型开发

开发者可直接基于源代码构建容器镜像，跳过 Dockerfile 编写步骤，加速本地开发-测试循环。

CI/CD 流水线集成

作为标准化构建环节嵌入 CI/CD 流程（如 GitHub Actions、GitLab CI、Jenkins），实现"代码提交→自动构建→镜像推送"的全自动化。

多语言应用构建

统一多语言项目的容器化流程，避免为不同语言维护差异化的 Dockerfile。

团队标准化构建

为团队提供一致的构建环境，减少"本地可运行、构建后不可运行"的环境差异问题。

降低 Dockerfile 维护成本

适用于希望减少 Dockerfile 维护工作量（如基础镜像更新、安全补丁管理）的团队或项目。

详细使用方法和配置说明

前置依赖

使用 Heroku CNB Builder 需安装以下工具：

• pack CLI：CNB 官方构建工具，用于触发构建流程（https://buildpacks.io/docs/tools/pack/）
• Docker 环境：确保 Docker 引擎已运行（用于本地镜像构建和运行）

基本使用示例

1. 构建应用镜像

在源代码根目录执行以下命令，使用 Heroku CNB Builder 构建镜像：

bash
pack build <镜像名称> --builder heroku/buildpacks:20

参数说明：

• <镜像名称>：自定义镜像标签（如 my-node-app:latest）
• --builder heroku/buildpacks:20：指定使用 Heroku CNB Builder（20 为 Stack 版本，对应 Heroku-20 运行时，其他版本如 22 对应 Heroku-22）

示例（构建 Node.js 应用）：

bash
# 克隆示例 Node.js 应用
git clone https://github.com/heroku/node-js-getting-started.git && cd node-js-getting-started

# 构建镜像
pack build my-node-app --builder heroku/buildpacks:20

2. 运行构建后的镜像

构建完成后，使用 Docker 运行镜像：

bash
docker run -p 3000:3000 docker.xuanyuan.run/my-node-app

访问 http://localhost:3000 即可查看应用。

自定义配置

设置环境变量

通过 --env 参数注入构建时环境变量（影响依赖安装、构建逻辑）：

bash
pack build my-app --builder heroku/buildpacks:20 \
  --env NODE_ENV=production \  # Node.js 环境（生产/开发）
  --env MAVEN_OPTS="-Xmx512m"  # Java Maven 构建参数

添加自定义 Buildpacks

通过 --buildpack 参数追加自定义 Buildpacks（优先级高于默认 Buildpacks）：

bash
# 使用本地自定义 Buildpack + Heroku 官方 Buildpacks
pack build my-app --builder heroku/buildpacks:20 \
  --buildpack ./my-custom-buildpack \  # 本地 Buildpack 路径
  --buildpack https://github.com/heroku/heroku-buildpack-nodejs  # Git 仓库 Buildpack

构建缓存配置

通过 --cache-volume 复用构建缓存，加速重复构建（需提前创建 Docker 卷）：

bash
# 创建缓存卷
docker volume create my-app-cache

# 使用缓存构建
pack build my-app --builder heroku/buildpacks:20 \
  --cache-volume my-app-cache

Docker Compose 集成示例

在 docker-compose.yml 中配置基于 Heroku CNB Builder 的构建流程：

yaml
version: '3.8'

services:
  app:
    # 基于 Heroku CNB Builder 构建
    build:
      context: .  # 源代码根目录
      builder: heroku/buildpacks:20  # 指定 builder 镜像
      args:
        # 构建时参数（传递给 pack build）
        BUILD_ENV: production
    ports:
      - "3000:3000"  # 端口映射
    environment:
      # 运行时环境变量（容器启动时生效）
      PORT: 3000

构建并启动服务：

bash
docker-compose up --build

常用配置参数说明

注意事项

1. 网络依赖：构建过程需联网下载依赖（如语言运行时、库文件），离线环境需提前配置私有依赖源。
2. Builder 版本：Heroku CNB Builder 镜像标签对应不同的 Heroku Stack 版本（如 20 对应 Ubuntu 20.04，22 对应 Ubuntu 22.04），需根据应用兼容性选择。
3. 构建缓存清理：若依赖版本更新后构建异常，可通过 pack build --no-cache 禁用缓存强制全量构建。
4. 安全扫描：构建产物镜像建议通过容器安全扫描工具（如 Trivy、Clair）检查漏洞，及时更新 Builder 镜像至最新版本。

相关资源

• https://github.com/heroku/cnb-builder-images（Heroku CNB Builder 源码及更新日志）
• https://buildpacks.io/docs/
• https://buildpacks.io/docs/tools/pack/cli/pack_build/
• https://devcenter.heroku.com/articles/buildpacks（支持的语言和框架详情）