Ruby on Rails 开发容器（Dev Container）从零上手：用 rails-new 一键搭建容器化开发环境

本文以仓库内 getting_started_with_devcontainer.md 官方指南为骨架，结合 railties 中 devcontainer 命令与生成器的真实实现，为你完整讲解「如何在完全不于本机安装 Ruby 的前提下，用开发容器（Dev Container）跑起一个 Rails 应用」。读完后你将掌握：Docker、VS Code、rails-new 三件套的安装与分工，如何生成带 .devcontainer 配置的全新 Rails 工程，如何用 VS Code 一键进入容器环境，以及 Rails 官方为现有应用提供的 rails devcontainer 生成命令与背后的配置项逻辑。

对于 Rails 开发者来说，「本机先装好 Ruby、再装 Rails、再处理数据库与各种依赖」是历史上最劝退的一步。而开发容器（Dev Container）的引入改变了这一流程：应用运行在一个预配置好的容器里，你的机器只需要 Docker 与一个支持 Dev Containers 的编辑器（典型是 VS Code），就能拥有完整、干净、可复现的开发环境。本指南将带你从零走通这条路，并深入仓库源码看看 Rails 究竟为你生成了什么。

开发容器能解决什么问题

本指南的目标是在你本机没有安装 Ruby、Rails 及其依赖的情况下，让 Rails 应用快速跑起来。Dev Container 本质是一套开放的规范（由 containers.dev 定义）：项目根目录下的 devcontainer.json 描述「如何访问或创建一个带有既定工具链与运行时栈的开发容器」，Docker 负责承载容器，VS Code 则负责把编辑器、终端、调试器、扩展全部「搬进」容器内工作。

与传统在本机安装方案相比，它是对 Getting Started 入门指南 中「Creating a New Rails App」方案的替代路径——因此官方建议：先按本指南跑通容器环境，再回头跟着 Getting Started 指南继续构建你的应用。

环境准备：Docker、VS Code 与 rails-new

要搭建这套环境，需要安装三样工具，各司其职：

1. Docker：dev container 的运行时底座。它是一款用于开发、交付、运行应用的开源平台。按官方文档在你的操作系统上安装 Docker Desktop 即可，安装完成后启动 Docker 应用让引擎运行起来。
2. VS Code 与 Dev Containers 扩展：VS Code 的 Dev Containers 扩展允许你把任意文件夹「打开进」容器（或挂载进容器）并享受完整编辑器能力。项目中的 devcontainer.json 正是告诉 VS Code 如何创建并进入这个「工具与运行时都被定义好」的容器——包括快速拉起容器、访问终端命令、调试代码、使用扩展。安装好 VS Code 后，再从扩展市场安装 Dev Containers 扩展即可。
3. rails-new：这是让「本机零 Ruby」成为可能的关键工具。它本身借助 Docker 来生成 Rails 应用，由 Docker 负责为你安装正确的 Ruby 与 Rails 版本，无需在本机安装 Ruby。按 rails-new 项目 README 中的安装说明完成安装。

一句话概括三者关系：rails-new 负责生成工程，Docker 负责运行环境，VS Code 负责接入这个环境并充当日常开发入口。

生成带 Dev Container 配置的 Store 应用

Rails 内置了一系列生成器（generators），其中「新应用生成器」负责生成全新 Rails 工程的骨架，让你不用手写基础结构。rails-new 工具在底层调用的正是 Rails 的这套生成器。

在终端进入你有权限创建文件的目录，执行：

$ rails-new store --devcontainer

该命令会在 store 目录下生成一个名为 Store 的 Rails 应用。--devcontainer 是关键选项：它让生成的工程自带一套完整可用的 dev container 配置。如果想知道生成器支持的全部命令行选项，可以随时运行 rails-new --help。

生成完成后进入工程目录：

$ cd store

store 目录里会有构成 Rails 应用结构的一批生成文件与目录，教程的大部分工作都发生在 app 目录中；关于整个目录结构的完整讲解，可以继续阅读 Getting Started 指南。

从源码看 rails-new 到底生成了什么

在仓库的 app_generator.rb 中，可以确认应用生成器对 devcontainer 的集成方式：当生成应用并选择了 devcontainer 时，它收集 app_name、数据库适配器、是否使用 Active Storage / Redis / Kamal / Node 等选项后，委托给 Rails::Generators::DevcontainerGenerator 执行。

而 devcontainer_generator.rb 的 create_devcontainer 会基于模板创建三个文件：

• .devcontainer/devcontainer.json：容器入口配置（指向 compose、声明 feature、环境变量、端口转发等）；
• .devcontainer/Dockerfile：开发镜像定义；
• .devcontainer/compose.yaml：编排应用容器与依赖服务（数据库、Redis 等）。

模板文件位于 railties/lib/rails/generators/rails/devcontainer/templates/devcontainer，分别对应 devcontainer.json.tt、Dockerfile.tt、compose.yaml.tt。也就是说，rails-new store --devcontainer 本质上是通过 Rails 应用生成器 + DevcontainerGenerator 的一次「模板渲染」，模板根据你应用的实际配置（是否用 PostgreSQL、Redis、Capybara 系统测试等）决定生成的容器内容。

在 Dev Container 中打开 Store 应用

新应用已经自带配置好的 dev container。启动 VS Code 并打开 store 目录后，VS Code 会检测到 dev container 配置文件并弹出提示，点击绿色的 "Reopen in Container" 按钮即可创建并进入容器。

容器初始化完成后，你的开发环境即就绪：Ruby、Rails 与全部依赖都已安装好，VS Code 变成你进入该容器的工作入口——运行代码、跑测试、启动应用都在容器内进行。

在 VS Code 内置终端里验证 Rails 是否可用：

$ rails --version
Rails 8.2.0

看到版本号输出即表示环境打通，接下来就可以回到 Getting Started 指南，在容器内开始构建你的 Store 应用了。

生成的 devcontainer.json 都包含什么

以仓库中 Rails 官方用于自身开发的 .devcontainer/devcontainer.json 为参照，这类配置文件的典型要素包括：

• dockerComposeFile / service / workspaceFolder：声明使用 compose.yaml 编排，工作目录挂载到 /workspaces/<工程名>；
• features：按需注入附加能力，例如 GitHub CLI、Node.js、数据库客户端等（仓库自身开发环境还引入了 ghcr.io/rails/devcontainer/features/postgres-client）；
• containerEnv：向容器注入数据库等服务的连接环境变量，例如 PGHOST、MYSQL_HOST、REDIS_URL、MEMCACHE_SERVERS，让应用无需硬编码即可连上 compose 中的依赖服务；
• forwardPorts：把容器内端口（如 Rails 默认的 3000）转发到本机供浏览器访问；
• postCreateCommand：容器创建后执行的初始化脚本。Rails 为新应用生成的模板默认执行 bin/setup --skip-server（见 devcontainer.json.tt）；而仓库自身的配置则调用 .devcontainer 下的 boot.sh 完成自定义初始化。

从源码看容器配置如何随应用「自适应」

devcontainer_command.rb 展示了 Rails 为已存在应用补充 dev container 配置的思路：运行 bin/rails devcontainer 时，命令会读取当前应用的实际配置，把以下探测结果交给生成器：

• 数据库适配器（mysql2 归一为 mysql，其余如 postgresql、sqlite3 原样透传）；
• 是否使用 Active Record、Active Storage；
• 是否因 Action Cable / Active Job 而需要 Redis（使用 Solid Cable / Solid Queue 时不再需要）；
• 是否存在系统测试（test/application_system_test_case.rb）；
• 是否存在 .node-version（决定是否引入 Node feature）；
• 是否存在 config/deploy.yml（决定是否引入 Kamal / Docker-outside-of-Docker）。

生成器侧（devcontainer_generator.rb）再据此拼装：

• container_env：系统测试场景注入 CAPYBARA_SERVER_PORT=45678 与 SELENIUM_HOST；Redis 场景注入 REDIS_URL=redis://redis:6379/1；有数据库服务时注入 DB_HOST；Kamal 场景透传 KAMAL_REGISTRY_PASSWORD；
• forward_ports：默认转发 3000，PostgreSQL（5432）、MySQL 与 Redis（6379）按需追加；
• features：默认加入 GitHub CLI，Active Storage 场景附加 Rails 官方的 activestorage feature，系统测试由 Selenium 支撑（并把对应 Gem 加入依赖）；
• 若使用 PostgreSQL，还会用 devcontainer 专用的 postgresql.yml 模板 重写 config/database.yml，让连接走容器内 host 而非本机 socket；
• 系统测试的 application_system_test_case.rb 会被改写为「容器内远程 Selenium、容器外本机 headless」的双模式逻辑。

这套「探测-生成」机制，正是 Rails 8 时代新应用默认自带 dev container 体验的底层来源：rails-new 是简化入口，bin/rails devcontainer 则服务于既有应用补齐配置。

场景化补充：仓库如何为自己的开发容器做回归保障

值得注意的是，Rails 官方仓库自身也采用 Dev Container 进行开发（.devcontainer 下的 devcontainer.json 与 devcontainer-lock.json），并为容器配置维护了专门的测试保障：工作流 devcontainer-shellcheck.yml 对容器脚本做静态检查，devcontainer-smoke-test.yml 执行冒烟测试；生成器的行为分别由 devcontainer_generator_test.rb 与 devcontainer_command_test.rb 覆盖。这说明「生成的 devcontainer 配置」本身也是被 Rails 持续验证的一等公民，你可以放心把这一机制用在真实项目里。

小结

从「本机无 Ruby」到「容器内跑通 Rails 8」，核心路径只有三步：装好 Docker、VS Code（含 Dev Containers 扩展）与 rails-new；用 rails-new store --devcontainer 生成工程；在 VS Code 中点击 "Reopen in Container"。若你的项目是已经存在的 Rails 应用，则可在工程内运行 bin/rails devcontainer，让 Rails 依据当前应用的数据库、队列、测试等真实配置自动补全 .devcontainer 配置。环境的复用与一致性问题，就此交给容器解决——这正是 getting_started_with_devcontainer.md 想要传达的核心工作流。