git 无法在运行时自动切换配置，必须通过 ci/cd 构建时注入分支名变量（如 github_head_ref），再由构建工具（如 vite）读取并生成对应环境配置；本地 git checkout 不触发任何配置变更。
能实现，但必须靠构建时注入，不能靠 Git 本身在运行时“自动切换”。Git 只管代码快照和历史，不参与环境配置决策；真正起作用的是 CI/CD 流程中对 branch name 的解析与变量传递。
为什么 Git checkout 无法自动加载对应测试环境配置
Git 的 checkout 或 switch 只改变工作区文件内容，不执行任何逻辑判断或配置替换。所谓“根据分支名切换配置”，本质是构建阶段的策略——不是 Git 做的，而是你写的 CI 脚本或构建工具做的。
- 常见误解：以为在
feature/login分支里放一个.env.test文件，切过去就自动生效 → 实际上，前端框架（如 Vite）或后端服务（如 Node.js）默认不会读取它，除非你显式写逻辑去加载 - 真实依赖链：
git push feature/login→ GitHub Actions 检测到分支名 → 提取login作为标识 → 注入ENV_NAME=login环境变量 → 构建脚本用该变量决定加载哪套配置 - 如果跳过 CI 直接本地
git checkout，没有任何机制会触发配置变更，除非你额外加了 git hook（但不推荐，不可靠且难维护）
Vite / Webpack 构建时如何基于 branch name 注入配置
核心是把分支名转成构建参数，再让打包工具消费。以 Vite 为例，vite.config.ts 支持函数式配置，可读取环境变量：
Conventional Git
下载
Conventional Commits v1.0.0 分支、工作树命名及提交信息规范，适用于 GitHub 与 GitLab 项目，用于创建分支和命名工作树等场景。
export default defineConfig(({ mode }) => {
const branchName = process.env.GITHUB_HEAD_REF || 'main'; // GitHub Actions 中可用
const base = branchName.startsWith('feature/')
? `/feature/${branchName.split('/')[1]}/`
: '/';
<p>return {
base,
define: {
<strong>ENV</strong>: JSON.stringify(branchName),
}
};
});</p>
-
GITHUB_HEAD_REF是 GitHub Actions 自动注入的变量，值为当前 PR 或 push 的分支名（如feature/login） - 本地开发时这个变量为空，需 fallback 到
main或读取git rev-parse --abbrev-ref HEAD（需 shell 脚本预处理） -
define会把__ENV__注入到运行时代码中，可用于条件加载 API 地址：const apiBase = __ENV__.includes('feature') ? 'https://test-api.example.com' : 'https://api.example.com'; - 注意：不要在
define中传敏感信息，它会暴露在前端源码里
CI/CD 中提取 branch name 并映射到环境变量的典型写法
GitHub Actions 的 workflow_dispatch 和 push 触发器都提供 github.head_ref，但不同场景下变量名不同：
- PR 场景：
${{ github.head_ref }}（来源分支名） - Push 场景：
${{ github.ref_name }}（即分支名，refs/heads/feature/login需用cut -d'/' -f4-截取） - 推荐统一处理方式：在 job step 中用 shell 提前解析并设为 env：
steps:
- name: Extract branch identifier
run: |
BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}
IDENTIFIER=$(echo "$BRANCH" | sed 's|feature/||; s|test/||')
echo "IDENTIFIER=$IDENTIFIER" >> $GITHUB_ENV
shell: bash
- 这样后续所有步骤都能用
${{ env.IDENTIFIER }}，比如传给vite build的--mode参数 - 避免在多个地方重复解析，也防止正则写错导致
base路径出错（例如误把feature/login-v2解成login-v2却没同步更新 Azure Blob 上传路径）
容易被忽略的路径一致性陷阱
分支名到 URL 路径的映射，必须在三个地方完全一致，否则资源 404：
- Vite 的
base配置（影响 HTML 中<script src></script>路径） - Azure Blob 或 Nginx 的静态文件存放路径（影响实际文件位置）
- Cloudflare 或 CDN 的缓存规则（如果对
/feature/*设置了特殊缓存策略，但 Vite 输出路径没匹配，就会缓存旧资源） - 示例错误：
feature/login分支构建时base设为/feature/login/，但上传脚本却把 dist 内容放到blob/test/project/feature-login/→ 最终请求/feature/login/assets/index.js返回 404
最稳妥的做法是：所有路径拼接逻辑只写一次，作为 CI 脚本里的变量统一引用，而不是在 Vite config、upload script、CDN 配置里各自硬编码。
