自动构建 (Railpack)

推送代码，获得容器 —— 无需 Dockerfile。

Application #auto#buildpack#railpack#git

Railpack 是现代的 buildpack 风格镜像构建器，自动检测你的语言和框架，生成 BuildKit 计划，并产出生产 OCI 镜像。Pier 包装它，让你可以从 Git URL 直接发布 Node、Python、Go、Rust、Ruby、PHP、Java、Deno、Bun、Elixir 等 —— 无需 Dockerfile、无 Nixpacks 锁定、无手动配置。

使用 Pier 部署

1 打开 Pier 控制台，点击 Add service。
2 从模板列表中选择 Auto-build (Railpack)。
3 选择版本、设置服务名称，Pier 会自动配置容器、存储和端口。
4 如需 HTTPS，请绑定域名。Traefik 会自动签发 Let's Encrypt 证书。

什么是 Railpack？

Railpack 是由 Railway 开发的开源镜像构建器，2024 年作为 Nixpacks 的继任者发布。它检查 Git 仓库，识别语言和框架，并使用 BuildKit 产出生产就绪的 OCI 镜像 —— 无需 Dockerfile。

结果是 Heroku 和 Railway 开创的 “推送代码，获得容器” 体验，但建立在现代基础设施上：BuildKit 的并行 LLB 执行、细粒度层缓存，以及最小的语言特定基础镜像，而非 Nixpacks 发布的重型 Nix store。典型的 Railpack 镜像比等效的 Nixpacks 输出小 20-80%，缓存命中时重建速度快 2-5×。

Pier 将 Railpack 包装为 “Auto-build” 服务模板。你给它 Git URL、端口和（可选）启动命令 —— Pier 克隆仓库、运行 Railpack、构建镜像，并在 Traefik 下使用 TLS 发布。从 git push 到上线 URL 的整个循环，根据项目大小和缓存状态需要 30-120 秒。

Pier 如何部署它

当你创建一个 Auto-build 服务时，Pier:

在选定的分支克隆配置的 Git URL。
在源代码上运行 railpack build —— Railpack 检查、规划并生成为你的服务打标签的 OCI 镜像。
将镜像存储在 Pier 的本地注册表中，并在暴露的端口上启动容器。
连接 Traefik，使服务可在其分配的域名上访问（如果附加自定义域名，则带自动 Let’s Encrypt TLS）。

仓库根目录的 railpack.json 让你覆盖 Railpack 自动检测的任何内容 —— 语言版本、系统包、install/build/start 命令、构建时 env 变量。大多数项目需要零配置。

Webhook 重新部署：配置你的 Git 主机 POST 到该服务的 Pier 重新部署 webhook，对监视的分支的每次推送都会自动重建和上线。

何时不要使用 Railpack

如果你已经有可用的 Dockerfile，保留它 —— 使用 Dockerfile 模板。手工调优的 Dockerfile 在特定应用的镜像大小、层控制和安全审查表面上击败任何自动构建器。

如果你的构建需要异国系统包、自定义多阶段逻辑或非 OCI 工件（init 系统、 supervisord 栈、多二进制 distroless），Dockerfile 也是正确的答案。

对于来自注册表的预构建镜像 —— 使用 Docker Image 模板。对于一起定义的多容器栈 —— Docker Compose。Railpack 专门适合 “我有一个仓库、我想要一个容器、我不想编写 Dockerfile 行” 的场景。

核心功能

零配置语言检测

从包文件（package.json、requirements.txt、go.mod、Cargo.toml、Gemfile、composer.json）检测 Node、Python、Go、Rust、Ruby、PHP、Java、Deno、Bun、Elixir、Static 等。无需记忆 buildpack 列表。

BuildKit 原生

生成由 BuildKit 执行的 LLB（low-level build）计划 —— 并行阶段、细粒度层缓存、frontend 隔离。相比传统 buildpack，重复构建快 30-80%。

比 Nixpacks 更小的镜像

典型的 Railpack 镜像比等效的 Nixpacks 输出小 20-80%，因为跳过 Nix store 层并按语言使用最小 Debian 或 Alpine 基础镜像。

框架感知

了解 Next.js、Astro、Vite、Nuxt、Remix、SvelteKit、Django、Flask、FastAPI、Rails、Laravel、Phoenix —— 自动选择正确的 install / build / start 命令。

静态站点模式

检测纯静态输出（Astro、Vite、Hugo、Jekyll）并发布 `nginx` 运行时而非 Node 服务器 —— 5 MB 镜像，微秒级冷启动。

覆盖友好

在仓库根目录放置 `railpack.json` 来固定版本、添加系统包、覆盖 install/build/start 命令、设置 env 变量。只覆盖你需要的，其余使用默认。

应用场景

Push-to-deploy 工作流

将仓库连接到 Pier，推送到 main → Railpack 自动构建 → 服务上线。无 CI YAML，无 Dockerfile 维护。

多语言团队

一个模板处理多语言 monorepo 中的每个服务。后端 Go 服务、前端 Next.js、ML Python worker —— 同一构建器，同一 UX。

从 Heroku / Render / Railway 迁移

为 Heroku / Render / Railway buildpack 设计的应用可以零或近零更改地移植到 Railpack。相同约定（Procfile、package.json scripts、requirements.txt）。

SSR + 静态并存

一个 `output 为 server` 的 Astro 站点运行 Node SSR；同一仓库设为 `output: 'static'` 时发布 nginx 容器 —— Railpack 根据构建输出正确选择。

快速演示和原型

在一分钟内从任何 GitHub 仓库启动一个可用的 URL。对 PR 预览、黑客松、客户演示有用。

代码示例

部署 Next.js 应用（无配置） bash

# 在 Pier:
# 1. 新服务 → Auto-build (Railpack)
# 2. Git URL: https://github.com/you/my-next-app.git
# 3. 分支: main
# 4. 端口: 3000
# 5. 部署。
#
# Railpack 检测 Next.js，运行:
#   npm ci → npm run build → npm run start
# 结果: 生产 OCI 镜像，约 120 MB。

railpack.json 覆盖 json

{
  "$schema": "https://schema.railpack.com",
  "provider": "node",
  "packages": {
    "node": "22",
    "pnpm": "9"
  },
  "aptPackages": ["ffmpeg", "imagemagick"],
  "buildCommand": "pnpm run build",
  "startCommand": "pnpm start",
  "env": {
    "NODE_ENV": "production"
  }
}

多语言 monorepo（根配置） json

{
  "provider": "python",
  "packages": { "python": "3.12" },
  "installCommand": "pip install -r requirements.txt",
  "startCommand": "uvicorn app:app --host 0.0.0.0 --port $PORT"
}

静态站点快捷方式 json

{
  "provider": "static",
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

对比

vs Dockerfile（本目录）	Dockerfile 给你 100% 控制，但你需要编写和维护构建逻辑。Railpack 为你编写，并在你需要覆盖之前保持不打扰。需要异国系统包或多架构构建时用 Dockerfile；其他一切用 Railpack。
vs Nixpacks（Railway 之前的构建器）	Nixpacks 开创了 auto-detect-and-build 模式，但通过发布 Nix store 产生大镜像。Railpack 是继任者 —— 更小镜像、更快缓存、更简单覆盖、现代 BuildKit frontend。
vs Heroku Buildpacks / Cloud Native Buildpacks	CNB 是有丰富生态的开放标准，但构建较慢且覆盖曲线更陡（project.toml、buildpack 排序）。Railpack 更简单、更快、有主见。
vs 手动 Docker 镜像	手工调优的 Dockerfile 永远在它针对的特定应用的镜像大小 + 启动时间上获胜。Railpack 在迭代速度和服务统一性上获胜。

常见问题

Railpack 支持哪些语言？

Node、Python、Go、Rust、Ruby、PHP、Java（Maven/Gradle）、Deno、Bun、Elixir，以及用于预构建站点输出的 "static" provider。新的 provider 定期发布。

我把 railpack.json 放在哪里？

在仓库根目录（package.json / pyproject.toml / etc. 旁边）。Railpack 在语言检测之前读取它并使用其字段作为覆盖。文件中所有内容都是可选的。

如何设置运行时环境变量？

在服务上使用 Pier 的 env-vars UI —— 它们在容器启动时注入。`railpack.json` 的 `env` 块仅用于构建时变量。

是否支持私有包（npm、PyPI 等）？

是 —— 在 Pier 中将 NPM_TOKEN / PIP_INDEX_URL / 等设置为构建时 env 变量。Railpack 将它们作为 secret 传递到 BuildKit 构建上下文中，不烘焙到最终镜像。

构建缓存行为？

BuildKit 层缓存位于 Pier 主机上。首次构建是完整的；只要 lockfile 和源哈希匹配，后续构建重用 install/build 层。增量推送上典型 80%+ 缓存命中。

如何触发重建？

推送到配置的分支，Pier 的 webhook（如果接通）触发重建。或在服务 UI 中点击 "Redeploy" 按钮 —— 它拉取最新提交并重建。

我可以看到 Railpack 决定了什么吗？

是 —— 构建日志打印检测到的 provider、install/build/start 命令和 LLB 计划。如果检测选错了栈，在 `railpack.json` 中覆盖。

与 "从 Dockerfile 部署" 的区别？

用 Dockerfile 你写构建配方。用 Railpack 配方被推断。如果你已经有可用的 Dockerfile，使用 Dockerfile 模板 —— 没有理由切换。

在你的 VPS 上部署

部署此服务 →