heroku/buildpack-nodejs

Heroku Node.js Cloud Native Buildpack

镜像概述

Heroku Node.js Cloud Native Buildpack 是 Heroku 官方提供的 Cloud Native Buildpack（CNB）实现，专为构建 Node.js 应用程序设计。该 Buildpack 符合 Cloud Native Buildpacks 规范，能够自动检测 Node.js 应用结构，处理依赖管理、构建流程及环境配置，简化从源代码到容器镜像的构建过程，适用于各类 Node.js 应用的容器化构建场景。

核心功能与特性

• 自动应用检测：通过识别项目根目录下的 package.json 文件，自动检测 Node.js 应用类型。
• 多包管理器支持：兼容 npm、yarn 及 pnpm 等主流 Node.js 包管理器，自动根据锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml）选择对应工具。
• 依赖管理自动化：自动执行 npm install/yarn install/pnpm install 安装依赖，并支持依赖缓存以加速重复构建。
• 版本控制：可通过环境变量或 .nvmrc/.node-version 文件指定 Node.js 版本，确保构建环境一致性。
• 构建流程支持：自动执行 build 脚本（若 package.json 中定义），完成应用编译（如 TypeScript 转译、前端资源打包等）。
• 环境配置：支持通过环境变量注入构建时/运行时配置，适配不同部署环境需求。

使用场景

• 开发环境快速构建：本地开发时，通过 Buildpack 快速将源代码构建为可运行容器，避免手动编写 Dockerfile。
• CI/CD 流程集成：嵌入持续集成/持续部署 pipeline，实现代码提交后自动构建容器镜像并推送至仓库。
• 标准化部署：统一团队构建流程，确保不同开发者/环境下构建的镜像一致性，减少"在我机器上能运行"问题。

使用方法与配置说明

前提条件

• 安装 pack CLI（Cloud Native Buildpacks 官方构建工具）
• 安装 Docker 并确保 Docker 服务运行

基本使用流程

1. 准备 Node.js 项目
   确保项目根目录包含 package.json 文件，示例项目结构：

   my-node-app/
   ├── package.json
   └── index.js
   

2. 构建容器镜像
   使用 pack 命令结合 Heroku Node.js Buildpack 构建镜像：

   bash
   # 使用 Heroku 官方 builder（包含 Node.js 等多个 Buildpack）
   pack build my-node-app \
     --builder heroku/buildpacks:20 \
     --path ./my-node-app
   

   或直接指定 Node.js Buildpack（需配合基础 builder）：

   bash
   pack build my-node-app \
     --builder paketobuildpacks/builder:base \
     --buildpack heroku/nodejs \
     --path ./my-node-app
   

3. 运行构建后的镜像
   构建完成后，通过 Docker 运行镜像：

   bash
   docker run -p 3000:3000 my-node-app
   

配置参数与环境变量

通过 --env 或项目内 .env 文件设置环境变量，常用配置如下：

版本锁定

推荐通过以下方式锁定 Node.js 版本，确保构建一致性：

• 在项目根目录创建 .nvmrc 文件：

  20.10.0
  

• 或 .node-version 文件：

  20.10.0
  

参考链接

• 官方文档与源码：https://github.com/heroku/buildpacks-nodejs
• Cloud Native Buildpacks 规范：buildpacks.io
• pack CLI 使用指南：pack 文档