一、从一个让同事头疼的问题说起
大家应该都经历过这样的场景：项目一大了，git 分支就多。主干在搞新架构，旧版本分支还需要修 bug，实验性分支又换了另一套依赖。每次切换分支，大家第一件事不是写代码，而是折腾环境——装这个包、卸那个包、调 Node 版本、装插件、改配置，有时候一上午就搭进去了。更麻烦的是，每个人电脑里的环境还不一样，最后就会冒出那句经典台词：我本地跑得好好的呀。
这种问题的根源，是开发环境和分支没有绑定在一起。分支不同，环境就应该跟着不同。可手动配置又慢又容易出错，所以我们需要一种办法，让环境跟着分支自动变化。这时候，GitHub Actions 和 Codespaces 就成了非常顺手的工具。
简单打个比方：Codespaces 就像一台随开随用的云上电脑，而你仓库里的 devcontainer.json 就是这台电脑的点菜单。点菜单里写了用什么系统、装什么软件、开什么端口、装什么插件，GitHub 就照着这份菜单去准备环境。如果能让不同分支自动携带不同菜单，那不就等于每个人切分支时，环境也被自动切换好了吗？
这个思路听起来很妙，但具体要怎么做呢？别急，下面我们一步步拆开来讲。
二、先认识 Codespaces 的菜单
在动手写自动化之前，至少得知道 Codespaces 是基于什么配置来工作的。它认准的是仓库根目录下 .devcontainer 文件夹里的一份 devcontainer.json 文件。你可以在里面配置很多东西，比如：
image：使用的开发容器镜像，也就是这台云电脑的基础系统，比如基于 Node.js 20 的官方开发镜像extensions：打开 Codespaces 后会自动安装的 VS Code 插件列表settings：VS Code 的编辑器设置，比如保存时自动格式化postCreateCommand：容器创建完成之后要自动执行的命令，比如安装依赖forwardPorts：需要暴露的端口features：一些增强功能，比如往容器里塞一个 Docker
只要 Codespaces 在启动时读到这份 JSON 文件，它就会按照文件内容准备环境。所以，我们的自动化目标很清楚：让不同分支上出现的 devcontainer.json 内容不一样。
三、动态生成的整体玩法
既然 Codespaces 只认仓库里的配置文件，那我们就想办法让这个文件随分支变化而变化。我常用的套路是：用 GitHub Actions 监听分支的 push 事件，在 workflow 里判断当前是哪个分支，然后组装出一份新的 devcontainer.json，最后把这个文件自动提交回当前分支。
这样，当你新建一个分支、往上面推代码时，Actions 就会像小管家一样，默默把环境配置文件改好。等你再打开 Codespaces，它读取到的是小管家刚刚准备好的新菜单。
这个动作很像一个连锁反应：分支推进 → Actions 被触发 → 读取分支信息 → 确定需要什么环境 → 生成配置 → 提交回去 → Codespaces 创建新环境。每一步都不需要人动手。
有的读者可能会担心：这不就是往仓库里反复提交文件吗？会不会很乱？别担心，只要控制好触发条件和提交频率，这个问题完全能解决，后面我会专门说注意事项。
四、用 GitHub Actions 实现基础自动化
4.1 先看看 Actions 怎么识别分支
在写完整示例前，我们先看一个非常简单的片段。这个片段要做的事情就一件：拿到当前分支名，并且根据分支名设置几个环境变量。这段逻辑是整个自动化的地基。
# 技术栈：GitHub Actions workflow（YAML）
name: 识别分支环境参数
# 当你把代码推送到任意分支时触发
on:
push:
branches:
- '**'
jobs:
detect:
runs-on: ubuntu-latest
steps:
# 用官方 checkout 动作把我们仓库的代码拉到临时机器里
- name: 拉取代码
uses: actions/checkout@v4
# 下面这个步骤是核心：从 GITHUB_REF 里把分支名抠出来
- name: 识别当前分支
id: vars
run: |
BRANCH="${GITHUB_REF#refs/heads/}"
echo "当前分支是 $BRANCH"
if [ "$BRANCH" = "main" ]; then
echo "node_ver=20" >> "$GITHUB_OUTPUT"
echo "pkg=pnpm" >> "$GITHUB_OUTPUT"
elif [ "$BRANCH" = "dev" ]; then
echo "node_ver=18" >> "$GITHUB_OUTPUT"
echo "pkg=npm" >> "$GITHUB_OUTPUT"
else
echo "node_ver=22" >> "$GITHUB_OUTPUT"
echo "pkg=pnpm" >> "$GITHUB_OUTPUT"
fi
上面的脚本里，GITHUB_REF 是 Actions 自动提供的一个变量，形如 refs/heads/main。我们通过 #refs/heads/ 把前缀去掉，剩下的就是单纯的分支名。然后根据分支名把 Node 版本和包管理器写到输出参数里，后面的步骤就可以直接引用这些参数。
4.2 完整示例：按分支生成 devcontainer.json
下面这个示例就完整多了。它能在 push 到任意分支时触发，按照分支名生成不同内容的 devcontainer.json，然后自动提交并推回当前分支。
# 技术栈：GitHub Actions workflow（YAML）
name: 按分支生成Codespaces配置
# 触发条件：手动触发 + 任意分支push
on:
workflow_dispatch:
push:
branches:
- '**'
jobs:
generate:
runs-on: ubuntu-latest
# 赋予工作流写仓库内容的权限，才能自动提交配置
permissions:
contents: write
steps:
- name: 拉取仓库代码
uses: actions/checkout@v4
# 第一步：识别分支并把分支名缓存成环境变量
- name: 获取分支信息
id: branch_info
run: |
BRANCH="${GITHUB_REF#refs/heads/}"
echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
# 第二步：根据分支名生成配置内容
- name: 生成 devcontainer.json
id: build_config
run: |
BRANCH="${{ steps.branch_info.outputs.branch }}"
mkdir -p .devcontainer
# 不同分支使用不同的环境镜像和插件
if [ "$BRANCH" = "main" ]; then
IMAGE="mcr.microsoft.com/devcontainers/javascript-node:20"
EXTRAS="dbaeumer.vscode-eslint"
elif [ "$BRANCH" = "dev" ]; then
IMAGE="mcr.microsoft.com/devcontainers/javascript-node:18"
EXTRAS="esbenp.prettier-vscode"
else
IMAGE="mcr.microsoft.com/devcontainers/javascript-node:22"
EXTRAS="ms-vscode.vscode-typescript-next"
fi
# 用 heredoc 把配置写进文件，注意里面的变量会被替换为实际值
cat > .devcontainer/devcontainer.json <<EOF
{
"name": "dev-env-$BRANCH",
"image": "$IMAGE",
"customizations": {
"vscode": {
"extensions": [
"$EXTRAS"
]
}
},
"settings": {
"editor.formatOnSave": true
},
"postCreateCommand": "npm install"
}
EOF
echo "已经生成 .devcontainer/devcontainer.json"
cat .devcontainer/devcontainer.json
# 第三步：把生成的配置提交回当前分支
- name: 提交并推送配置
run: |
BRANCH="${{ steps.branch_info.outputs.branch }}"
git config user.name "github-actions-bot"
git config user.email "actions@github.com"
git add .devcontainer/devcontainer.json
# 如果没有变化，就不要产生无意义的提交
if git diff --cached --quiet; then
echo "配置没有变化，跳过提交"
else
git commit -m "自动更新Codespaces环境配置"
git push origin HEAD:"$BRANCH"
fi
这段 workflow 里有一个细节我很喜欢：它会判断 diff 有没有变化。如果这次生成的内容和之前一样，它就不会产生一个新的提交。这样能避免几百个“自动更新环境配置”的垃圾提交堆满仓库。
你可能会问，生成完配置之后，Codespaces 是立刻就用上新配置了吗？并不是。Codespaces 是在创建新环境的时候才读取配置文件。如果旧环境还开着，它不会自动更新，除非你手动重建容器。所以，正确的用法是：切到一个新分支，让 Actions 先跑完，然后再打开 Codespaces，这样环境才准确。
五、把玩法升级：不只改镜像，还能按分支定制更多东西
前面的例子只是改了镜像和插件。其实，只要是 devcontainer.json 里支持的内容，都可以用同样的方式动态生成。比如，你可以让 main 分支的容器里带一个数据库工具，让 dev 分支带一个 HTTP 调试工具，让每个功能分支暴露不同端口。思路都是一样的：先分支判断，再拼 JSON，最后写入文件。
5.1 给特定分支添加 features
features 是开发容器里特别方便的一个东西，相当于给基础镜像再加一层能力，比如往容器里装 Docker。下面的例子展示了如何在 workflow 里根据分支添加特征。
# 技术栈：GitHub Actions workflow（YAML）
name: 生成带特性的环境配置
on:
push:
branches:
- '**'
jobs:
generate:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: 提取分支名
id: branch
run: |
BRANCH="${GITHUB_REF#refs/heads/}"
echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
- name: 生成带features的配置
run: |
BRANCH="${{ steps.branch.outputs.branch }}"
mkdir -p .devcontainer
if [ "$BRANCH" = "release" ]; then
# 发布分支需要 Docker 环境，方便打镜像
FEATURES='"ghcr.io/devcontainers/features/docker-in-docker:2": {}'
else
# 其他分支不启用额外特性
FEATURES='{}'
fi
# 组装 JSON 文件
cat > .devcontainer/devcontainer.json <<EOF
{
"name": "feature-env-$BRANCH",
"image": "mcr.microsoft.com/devcontainers/universal:2",
"features": $FEATURES,
"forwardPorts": [3000, 8080]
}
EOF
cat .devcontainer/devcontainer.json
- name: 提交配置
run: |
git config user.name "bot"
git config user.email "bot@example.com"
git add .devcontainer/devcontainer.json
git diff --cached --quiet || git commit -m "更新分支features"
git push origin HEAD:"${{ steps.branch.outputs.branch }}"
通过这个方式，你甚至可以为每个功能分支临时打开某个端口，或者让某些分支拥有数据库客户端，这一点特别像按需给不同开发环境配菜。
六、这个玩法好在哪里，又有什么局限
6.1 优点
最直观的好处是省时间。老开发不用再一遍遍教新人怎么配环境了，新同事打开 Codespaces，环境就是这个分支该有的样子。第二个好处是一致性。既然配置是 Actions 统一生成的，大家的环境自然就统一了，不会再出现这个环境能跑、那个环境不能跑的问题。第三个好处是省心。环境配置从“人记”变成“代码管”，你只需要把规则写进 workflow，剩下的事情交给自动化。
6.2 缺点
不过，它也不是没有麻烦。一方面，生成的配置文件会出现在仓库历史里，如果触发频繁，git 提交记录会变脏，需要靠跳过无变化提交来缓解。另一方面，Codespaces 启动需要时间，如果配置的镜像很大，开发人员可能等好几分钟才进入环境，这点和本地开发没法比。
另外，一旦 workflow 逻辑写复杂了，调试起来也不太直观。你很难在本地快速模拟 Actions 的行为，只能在推送后看运行日志，调一次就要等一次。不过这属于自动化流程的普遍问题，不算特别严重。
七、使用过程中一定要留意的几个坑
7.1 受保护分支不能直接推送
如果你的 main 分支开了分支保护规则，普通人不能直接推代码，那 workflow 里的 git push origin HEAD:main 就会失败。这时候可以换一种思路：别往同分支提交，而是专门开一个 codespaces-config 分支去存配置，或者改用 Pull Request 模式，让 Actions 把配置改动提交到一个新分支，再自动创建一个 PR。
7.2 Codespaces 不会实时读取配置
前面提到过，Codespaces 是在创建环境时读取配置文件，并不是文件一更新，正在运行的环境就立刻跟着变。如果你改完 devcontainer.json，想看到效果，记得在 Codespaces 里执行重建容器，或者把环境删掉重新创建。
7.3 分支名里的特殊字符
分支名不能乱放进 JSON，比如名字里如果有双引号，就会破坏整个 JSON 结构。所以在把分支名写进配置文件之前，建议先做一次转义或清理。比如写一个小函数，把 "、\、/ 这些字符替换掉，保证最终生成的 JSON 是合法的。
7.4 每次 push 都触发会产生噪音
如果一个分支频繁推送代码，Actions 就会一直跑，即使配置没变化，也会消耗运行时间。更稳妥的做法是给 work flow 加上路径过滤，比如只当 .devcontainer 目录或某个标记文件变化时才触发生成逻辑。或者你也可以只在 workflow_dispatch 时手动触发，想要生成环境时才运行一次。
7.5 注意 Actions 的并发问题
假设两个开发者同时往同一个分支推送代码，两个 workflow 同时去改 devcontainer.json，就有可能出现冲突。这种情况并不常发生，但一旦发生，其中一个提交可能会失败。解决方式很简单：在 workflow 里加一个 concurrency 配置，让同一分支同一时间内只运行一个任务。
八、写到最后
GitHub Actions 和 Codespaces 搭配起来，真的是一个很灵活的开发环境管理方案。你不需要买额外的服务器，也没有复杂的平台成本，只要会写 Yaml，就能根据仓库分支“变”出不同环境。现在很多团队已经不再满足于“一个仓库用一套环境”，而是希望每一个分支、每一个 PR 都能拥有独立且干净的环境。这种动态生成配置的思路，恰好可以有效做到这一点。
以后如果再遇到同事问：这个分支要用哪个 Node 版本？我该装哪些插件？你可以笑着说：别急，推上去，环境会自动准备好。这一步虽然只是把配置文件自动化了一小下，但给每天开发带来的省事程度，是大有改观的。
评论
围绕“使用GitHub Actions动态生成Codespaces配置，按仓库分支定制开发环境的自动化玩法”参与讨论