# 一个 JSON 文件，省下 FDE 驻场第一天

> 借助 Dev Containers 和 GitHub Codespaces，团队与客户工程师克隆仓库就能用上同一套工具。

原文: https://fdetimes.net/zh/tools/dev-containers-github-codespaces-shared-environment/

每个 FDE 在客户现场的第一个早上都听过这句话：“我机器上能跑，你那边怎么就不行？”接下来往往是大半天折腾 Python 版本、数据库驱动，以及某个忘了装的扩展。

Dev Containers 解决的正是这个问题，思路也很简单：把整个环境写进仓库里的一个文件。无论是你的同事还是客户的员工，打开仓库就能拿到同一套工具。

对前线部署工程师（FDE）来说，好处很实在。FDE 经常和客户的工程师并肩工作，他们不熟悉你的技术栈，也没时间去猜。如果他们克隆仓库后马上就能跑起第一条命令，联合工作一开始讨论的就是客户的问题，而不是环境配置问题。

## 一个 JSON 文件描述整个环境

Development Containers 是一项以 Microsoft 名义发布的开放规范，发布在 containers.dev。借助它，可以给容器加上开发工具和设置，把容器变成完整的开发环境。

最重要的文件是 devcontainer.json，也就是这项规范的主要格式。构建开发容器所需的元数据和设置都写在里面。

根据 GitHub Docs，这份配置放在仓库的 .devcontainer 文件夹中。也就是说，环境配置和其他代码一样可以提交、评审和回滚。

另一半是 GitHub Codespaces。每个 codespace 都是一个开发环境，运行在 GitHub 管理的虚拟机上的 Docker 容器里，读取的也是同一份配置文件。

## 搭建共享环境的五个步骤

假设你在为客户搭建一条数据处理管道。你的团队用 Mac，客户那边有两名工程师用公司配发的笔记本。与其发给他们一份冗长的 README，不如按下面五步来做。

**第 1 步。**在仓库根目录创建 .devcontainer 文件夹，在里面新建 devcontainer.json 文件。

**第 2 步。**选定镜像并固定下来。`image` 属性填的是容器镜像仓库中的镜像名，版本就在这里锁定。Chainguard 的 Adrian Mouat 解释过：tag 随时可能被指向另一个镜像，digest 则不可变。

**第 3 步。**添加全队都需要的扩展。完成后的文件如下：

```json
{
  "name": "customer-pipeline",
  "image": "mcr.microsoft.com/devcontainers/python@sha256:<your-verified-digest>",
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python"]
    }
  }
}
```

把 `` 换成镜像仓库中你实际测试过的那个镜像的 digest。刚起步时为了方便用 tag 没问题，但把仓库交给客户之前，要换成 digest。

**第 4 步。**在装有 Dev Containers 扩展的 VS Code 中打开仓库文件夹，执行“Dev Containers: Reopen in Container”。编辑器会按 devcontainer.json 构建容器，并在容器内重新打开该文件夹。

**第 5 步。**请一位从没碰过这个仓库的同事在自己的机器上打开它。凡是他们还得自己安装的东西，都写进文件并提交。这样才能确认文件是完整的。

如果团队给多个客户做的多个项目用的是同一套技术栈，就在所有仓库里使用同一个固定的镜像。每次升级只需测试一个镜像，而不是一堆各自漂移的环境。

## 本地还是 Codespaces：先问数据放在哪里

根据 VS Code 文档，在本地运行 Dev Container，需要机器上已安装并配置好 Docker。这件事最好在第一周就和客户提出来，原因有两个。

公司配发的笔记本往往限制安装软件；而 Docker Desktop 只对员工少于 250 人、年收入低于 10,000,000 美元的企业免费，规模较大的客户团队可能需要付费方案。

Codespaces 省掉了这一步，因为容器运行在 GitHub 的虚拟机上。代价是代码，可能还有样例数据，会放在 GitHub 的基础设施上。

对金融或医疗行业的客户来说，这个问题应该交给他们的安全团队，不能替他们拍板。好在同一份 devcontainer.json 在两边都能运行，选择并非一锤子买卖。

**要点:** 环境配置应该像代码一样提交和评审，而不是只存在于某个人的脑子里。

还有一个现实的限制：速度。大型仓库创建 codespace 可能要花一段时间。GitHub 提供预构建功能，预先装好源码、扩展和依赖，新的 codespace 启动更快。先给第一次创建计时，如果觉得慢，就开启预构建。

## 第一周就让共享环境失效的两个错误

第一个错误是让镜像跟着 tag 漂移。相隔一个月打开仓库的两个人，可能拿到两个不同的镜像，“环境完全一致”的好处也就没了。第 2 步的示例正是为了避免这种情况。

第二个错误更危险：把密钥写进 devcontainer.json。这个文件会提交到仓库，任何有读权限的人都看得到，客户的 API 密钥或数据库密码绝不能出现在里面。文件里只放工具配置；凭据应来自客户安全团队批准的密钥管理系统。

## 先学什么，如何展示这项技能

从最小可用的配置做起：一个固定的镜像加一份扩展列表。第一天别把所有东西都塞进去，让第 5 步告诉你还缺什么。

就职业发展而言，这项技能比想象中更容易展示。作品集仓库里有一个 .devcontainer 文件夹，能让招聘经理看到你会为下一个使用你代码的人着想。

在简历上，写一行引入 Dev Container 前后客户工程师上手各花了多长时间，远比在技能栏里列上 Docker 有分量，前提是你真的测过这个数字。岗位描述里提到“developer experience”或“onboard customer engineers”时，就是讲这个故事的地方。

优秀的 FDE 之所以让人记住，是因为他们离开后，客户自己也能把系统跑起来。一份好的 devcontainer.json，是从第一天起就做到这一点成本最低的办法。

**本周动手试试:**

- 在手头的一个仓库里加上 .devcontainer 文件夹和一份最小的 devcontainer.json（按 digest 固定的镜像加上所需扩展），然后请一位同事用 VS Code 打开。
- 在 GitHub Codespaces 中打开同一个仓库，从创建到跑起第一条命令计个时。如果很慢，读一读 GitHub 关于预构建的文档。
- 在简历或项目 README 里加一行具体信息，例如新工程师从克隆仓库到测试通过需要多长时间。

## 信源

- [Development Containers](https://containers.dev/)

- [devcontainers/spec: Development Containers Specification](https://github.com/devcontainers/spec)

- [Dev Container metadata reference](https://containers.dev/implementors/json_reference/)

- [Introduction to dev containers - GitHub Docs](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)

- [What are GitHub Codespaces? - GitHub Docs](https://docs.github.com/en/codespaces/about-codespaces/what-are-codespaces)

- [About GitHub Codespaces prebuilds - GitHub Docs](https://docs.github.com/en/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds)

- [Developing inside a Container - Visual Studio Code](https://code.visualstudio.com/docs/devcontainers/containers)

- [How I learned to stop worrying and love the latest tag (Adrian Mouat, Chainguard)](https://www.chainguard.dev/unchained/how-i-learned-to-stop-worrying-and-love-the-latest-tag)

- [Docker Plans FAQs | Docker](https://www.docker.com/pricing/faq/)
