whistle.env-switcher

whistle.env-switcher 是一个给 Whistle 用的多项目环境切换插件。

它的目标是替代手工维护的 rules.txt + values 方案，把“前端环境切换 + 服务端接口环境切换”统一收敛到一个插件里管理。

解决什么问题

• 一个插件配置里支持多个项目
• 同一个项目同时支持两类切换：
  • 前端环境：页面、静态资源、非内部接口请求走哪个前端地址
  • 服务端环境：命中指定路径前缀的接口请求走哪个后端环境
• 页面自动注入一个悬浮切换器，不需要手工改业务代码
• 支持 fetch、XMLHttpRequest、WebSocket、EventSource、navigator.sendBeacon
• 配置保存在插件里，不需要反复复制 Whistle Rules / Values

工作方式

插件会根据你配置的项目匹配规则，识别当前请求属于哪个项目，然后：

• 对页面请求和静态资源请求，按当前选中的 frontendTarget 转发
• 对命中 routeGroups[].prefixes 的接口请求，按当前选中的后端环境转发
• 对 HTML 页面自动注入一个环境切换小控件

当前版本默认不再往请求 URL 自动拼接内部 query 参数，而是：

• fetch / XHR 主要通过请求 header 传递环境信息
• WebSocket / EventSource / sendBeacon 通过 cookie 兜底识别环境
• query 参数仅保留为兼容旧链路和手工排查时的兜底能力

安装方式

从 npm 安装

发布到 npm 后，可以直接用安装到全局，然后打开whistle就会发现已经有这个插件了.

# 国内cnb
npm i -g whistle.env-switcher --registry=https://npm.cnb.cool/sojs/whistleplugin/-/packages/
# 走npmjs
npm i -g  whistle.env-switcher

也可以在 Whistle 的 Plugins 页面中直接输入 whistle.env-switcher 安装。

在 Whistle 中如何使用

1. 安装并启用插件
2. 打开 Whistle 的 Plugins 页面
3. 找到 whistle.env-switcher，进入它的 Option 页面
4. 在配置页中：
   • 直接粘贴 JSON
5. 保存配置
6. 打开你配置过的项目域名，例如 local.dev:8000
7. 页面加载后会自动出现悬浮环境切换器

保存配置之前，插件不会对请求做任何改写或注入。

配置方式

当前插件使用 JSON 配置。

根结构如下：

{
  "version": 1,
  "signalKeys": {
    "projectQueryKey": "__wes_p",
    "apiEnvQueryKey": "__wes_e",
    "projectHeaderKey": "x-whistle-env-project",
    "apiEnvHeaderKey": "x-whistle-env"
  },
  "projects": []
}

最小可用示例

{
  "version": 1,
  "signalKeys": {
    "projectQueryKey": "__wes_p",
    "apiEnvQueryKey": "__wes_e",
    "projectHeaderKey": "x-whistle-env-project",
    "apiEnvHeaderKey": "x-whistle-env"
  },
  "projects": [
    {
      "key": "local",
      "name": "本地项目",
      "enabled": true,
      "matchHosts": ["local.dev:8000"],
      "matchPathPrefixes": ["/"],
      "ui": {
        "reloadOnApiSwitch": true
      },
      "frontendTargets": [
        {
          "key": "local-front",
          "label": "本地前端",
          "color": "#2563eb",
          "target": "http://127.0.0.1:8000"
        },
        {
          "key": "test-front",
          "label": "测试前端",
          "color": "#7c3aed",
          "target": "https://test.example.com"
        }
      ],
      "defaultFrontendTargetKey": "local-front",
      "routeGroups": [
        {
          "key": "api",
          "name": "api",
          "prefixes": ["/api"],
          "defaultEnvKey": "default",
          "envs": [
            {
              "key": "default",
              "label": "本地环境",
              "color": "#64748b",
              "target": ""
            },
            {
              "key": "test",
              "label": "测试环境",
              "color": "#f59e0b",
              "target": "http://xxxxxx:8090/api"
            }
          ]
        }
      ]
    }
  ]
}

配置项说明

根级字段

version

• 配置版本号
• 当前固定为 1

signalKeys

• 定义运行时内部使用的 header / query key 名称
• 一般保持默认即可

字段说明：

• projectQueryKey
  • 项目标记对应的 query key
  • 现在主要用于兼容旧链路或手工排查
• apiEnvQueryKey
  • API 环境标记对应的 query key
  • 现在主要用于兼容旧链路或手工排查
• projectHeaderKey
  • fetch / XHR 请求中携带项目标识的 header 名
• apiEnvHeaderKey
  • fetch / XHR 请求中携带 API 环境标识的 header 名

projects

• 项目列表
• 一个配置里可以放多个项目

单个项目字段

key

• 项目唯一标识
• 会用于 cookie、localStorage、运行时内部识别
• 建议保持稳定，不要频繁改

name

• 项目展示名称
• 用于 Option 页面和页面悬浮切换器显示

enabled

• 是否启用该项目
• false 时该项目不会参与请求匹配

matchHosts

• 项目入口 host 列表
• 用于判断当前请求是否属于这个项目
• 支持精确匹配，例如：local.dev:8000
• 也支持简单的 *. 前缀匹配

matchPathPrefixes

• 项目入口路径前缀
• 当多个项目共用同一个 host 时，用它进一步区分项目
• 例如：["/admin"]

configPath

• 当前项目的运行时配置接口路径
• 该字段由插件根据 project.key 自动生成，不需要手动配置
• 生成规则：/__env_<projectKey>__
• 例如：key = "local" 时路径为 /__env_local__

ui.reloadOnApiSwitch

• 切换服务端环境后是否自动刷新页面
• true：切换后立刻刷新
• false：只更新选择状态，不自动刷新

frontendTargets

• 前端环境列表
• 当请求没有命中任何 routeGroups[].prefixes 时，会走这里选中的目标
• 页面、静态资源、其他非内部前缀请求都会使用这里的当前选择

每个 frontendTargets[] 项字段：

• key
  • 当前前端环境唯一标识
• label
  • 页面上展示的名称
• color
  • 悬浮切换器里显示的小圆点颜色
• target
  • 实际要转发到的前端地址
  • 例如：http://127.0.0.1:8000

defaultFrontendTargetKey

• 默认前端环境 key
• 首次进入项目、还没有用户选择时会使用它

routeGroups

• 服务端接口路由分组
• 每个分组通过一组路径前缀来识别“哪些请求属于这类接口”
• 一个项目可以有多个 route group

每个 routeGroups[] 项字段：

key

• 路由分组唯一标识
• 会参与 API 环境 cookie / localStorage 的 key 生成

name

• 分组展示名
• 用于页面切换器里显示

prefixes

• 当前分组命中的路径前缀列表
• 例如：["/api", "/gateway"]
• 请求路径命中其中任意一个前缀，就会被归到该分组

defaultEnvKey

• 当前分组默认使用的环境 key

envs

• 当前分组下可切换的环境列表

每个 envs[] 项字段：

• key
  • 环境唯一标识
• label
  • 页面上展示的环境名称
• color
  • 悬浮切换器显示用颜色
• target
  • 该环境的上游地址
  • 如果为空字符串，表示命中这个分组后不改写上游，直接透传原请求

路由规则说明

前端请求怎么走

如果请求属于当前项目，但路径没有命中任何 routeGroups[].prefixes：

• 使用当前选中的 frontendTarget
• 把页面和静态资源转发到这个前端地址
• 如果是 HTML 页面，还会自动注入悬浮环境切换器

服务端请求怎么走

如果请求路径命中了某个 routeGroups[].prefixes：

• 先找到命中的 route group
• 再读取当前选中的环境
• 最后把请求改写到该环境的 target

当前环境从哪里读取

服务端 API 环境优先级：

1. header
2. query（兼容兜底）
3. cookie
4. 分组默认环境

前端环境优先级：

1. cookie
2. 默认前端环境

页面悬浮切换器

插件会在匹配到的 HTML 页面中注入一个小控件，用来切换当前项目的前端环境和服务端环境。

支持：

• 拖动移动位置
• 自动保存位置
• 显示当前前端环境 / 服务端环境
• 点击后展开环境列表
• 点击页面其他区域关闭浮层

常见使用场景

场景一：本地前端 + 多套后端接口

• 页面和静态资源走本地开发服务
• /api 请求可以在本地 / 测试 / 线上后端之间切换

场景二：同一个后端前缀，不同项目独立配置

• project A 匹配 a.local.dev:8000
• project B 匹配 b.local.dev:8000
• 两个项目可以共用相同的接口前缀，但切换状态互不影响

场景三：一个项目多个接口域前缀

• /api-user 对应一个 route group
• /api-order 对应另一个 route group
• 页面切换器中分别独立切换

开发命令

npm install
npm run build
npm run dev
npm pack

调试插件

这边开发

npm run build
``

然后再whistle这边使用命令加载,指定whistle插件的父目录

```shell
w2 run -A E:/env-switcher-addon -p 8083

然后打开whistle就可以看到最新的插件在列表中了，如果你已经安装过，使用-A会优先使用本地开发挂在的插件。

更多文档

• docs/00-scope.md
• docs/01-architecture.md
• docs/02-config-schema.md
• docs/03-routing-matrix.md
• docs/08-usage.md
• docs/09-packaging-and-release.md