企业官网建设流程全解析

开发过程中最烦人的事之一，就是环境切换。前后端联调、多版本并行、测试环境轮流虐你——尤其当你同时维护两三个项目，每个项目还有 dev、test、staging 甚至本地 mock 环境时，改接口地址、切代理、清缓存、重启服务，这一套操作下来，一上午基本就没了。

EnvManage 就是冲着这个痛点去的。它是一套多环境开发代理管理工具，核心就一件事：把"切环境"这件事从人的记忆里拿出来，变成可控的配置和自动化的规则。只要前期把环境清单和路由规则配好，后面不管是切换后端地址、代理指定域名的流量，还是在本地起多个接口服务来回调试，都能变得非常机械、非常省心。

这篇文章不是官方文档，是我自己从零搭这个工具的完整记录，包括设计思路、核心模块是怎么拆的、配置格式怎么定、路由匹配怎么做，以及实测中遇到的那些文档里绝对不会写的坑。如果你也在被多环境切换折磨，或者想自己动手做一个类似的内部工具，这篇应该能给你不少可以直接落地的思路。

1. 为什么需要 EnvManage：多环境代理到底难在哪

先说场景。假设你在做前端开发，本地起了个 Vite 或者 Webpack 的 dev server，页面要请求后端接口。后端这位同事同时维护着两个版本，A 版本在老环境（api-a.example.com），B 版本在新环境（api-b.example.com）。今天你要联调 A 版本的登录模块，明天又要切到 B 版本看订单列表——这就是最常见的多环境并行。

这种场景下，传统做法是在代码里写一堆环境判断：

// 早期我干过这种事，现在想起来头都大 const API_BASE = process.env.NODE_ENV === 'development' ? (localStorage.getItem('env') || 'https://api-a.example.com') : 'https://api-b.example.com';

问题立刻出现：改环境要改代码、要刷新、要清缓存，尤其是 localStorage 存了旧值时，你根本不知道此刻跑的是哪个环境，接口报错了你连排查方向都定不了。

再往后一点，很多人会用 dev server 内置的 proxy 功能，比如 Vite 的server.proxy配置：

// vite.config.js export default { server: { proxy: { '/api': { target: 'https://api-a.example.com', changeOrigin: true, rewrite: path => path.replace(/^\/api/, ''), } } } }

这个方案比改代码强，但要切环境就得改配置文件并重启 dev server。更麻烦的是，如果同一个代理路径需要按小数量的参数或者按域名做不同转发，纯靠静态配置根本转不过来。团队里每个人各自改自己的配置文件，合并代码时冲突成一片，这几乎是必然的。

所以 EnvManage 的目标非常明确，就三条：

1. 把环境地址集中管理，不散落在代码、配置、脚本和同事的聊天记录里。
2. 让切换环境变成一个动作，而不是一串操作。
3. 让代理规则可编程，按域名、按路径前缀、按请求头，都能灵活转发。

这套工具本身不是银弹，但它把"多环境代理管理"从完全靠脑子记、靠手改的状态，变成了一套有结构、可审计、可团队共享的机制。

2. EnvManage 的整体架构：三个核心模块的分工

我一开始想得挺简单：写一个能切来切去的代理程序不就行了吗？实际做下来发现完全不是这么回事。EnvManage 拆成三个模块之后才变得清晰：环境注册中心、路由匹配引擎、代理转发器。

2.1 环境注册中心：一切环境信息的中枢

这个模块负责维护你所有环境的基础信息。每个环境有一个唯一标识，一组基础地址，还有一些属性标签。

我用 YAML 存配置，原因很简单：可读性好，git diff 友好，团队里不懂代码的人也能看懂。以下是我用的格式：

# envs.yaml - 环境注册中心示例 environments: - id: dev-local name: 本机开发环境 hosts: - 127.0.0.1:8080 - localhost:8080 tags: [local, dev] weight: 10 - id: dev-remote name: 远端联调环境A hosts: - api-a.example.com tags: [remote, dev, team-a] weight: 20 - id: staging name: 预发布环境 hosts: - api-staging.example.com tags: [remote, staging] weight: 30 - id: prod name: 生产环境 hosts: - api.example.com tags: [remote, prod] weight: 100

注意我加了weight字段。weight在这里不是负载均衡权重，而是环境选择的优先级。比如dev-local的 weight=10，意味着在没有任何手动指定时，工具优先把流量导到本地环境；但如果你手动指定了stage，那么这个指定优先级高于一切。这个设计解决了一个实际问题：本地能跑的就不要走远程，既省带宽又避免改远程数据。

2.2 路由匹配引擎：真正干活的决策者

路由匹配引擎的职责是回答一个问题：当前进来的这个请求，应该交给哪个环境？

它接收三个输入：

• 请求的域名（Host）
• 请求的路径（Path）
• 当前的工作模式（manual / auto / pinned）

我在第一版里只匹配域名，后来发现不够——同一个域名在不同路径下可能需要不同的后端。比如/api/auth/走 A 环境，/api/pay/走 B 环境。所以第二版切成了"域名 + 路径前缀"的联合匹配。

匹配顺序也有讲究，我用的是最长路径前缀优先：

/api/auth/login -> env-auth /api/auth -> env-auth /api/pay -> env-pay /api -> env-default

判断时先取最长匹配的规则，而不是第一个匹配的规则。这样/api/order/list在没有更具体规则时会掉到env-default，但/api/pay/create一定能落到env-pay。这个设计避免了"先定义谁、先匹配谁"的顺序陷阱。

2.3 代理转发器：流量真正穿过的通道

转发器实现的是最底层的 HTTP/HTTPS 转发能力。我基于 Node.js 的http-proxy来实现，因为它足够轻量、生态成熟，处理 WebSocket 转发也很方便。

它的核心职责有三块：

1. 接管本地 dev server 发出的流量，根据路由引擎的决定改写目标地址。
2. 保留必要的请求头——Host、Origin、Cookie、Authorization——只改写需要改写的字段。
3. 透传响应，并把后端返回的内容原样返回给浏览器，同时处理好 CORS 相关的响应头。

这个是代理转发器最关键的部分。处理不好，前端会出现一模一样的 401、跨域报错，你根本分不清是哪一层出的问题。

3. 环境切换的三种工作模式：手动、自动、固定

工具做出来之后，我被问得最多的问题是：你到底是自动切，还是手动切？我的答案是两种都要，而且可以混合用。EnvManage 提供了三种模式，分别应对不同场景。

3.1 手动模式：命令行的确定性

手动模式是最朴素的，适合那种"我就想明确知道此刻流量去哪"的场景。

envm use dev-remote --project shop-app

执行完以后，shop-app项目下所有未命中特殊规则的请求，一律转到api-a.example.com。这个操作会实时影响正在运行的 dev server，不需要重启，因为规则存储在运行内存中，代理转发器每次都会实时查询当前生效的环境。

手动模式的优点是可预期，缺点呢？太依赖人的操作。你忘了切，它就用上一次的环境，联调半天发现打错了库，这种事还是会发生。

3.2 自动模式：用分支名做环境推断

自动模式是 EnvManage最让我觉得"值回票价"的模块。原理不复杂：用 git 分支名推断应该走哪个环境。

我定了一套命名规范：

但分支名和环境名的对应不能硬编码死在代码里，那样团队改动命名规范就得改工具。我把它做成配置：

# envm.config.yaml branch_policy: - pattern: '^(main|master)$' env: prod - pattern: '^release/.+' env: staging - pattern: '^(feat|fix)/.+' env: dev-remote - pattern: '^test/.+' env: test

匹配使用正则表达式，按顺序优先级匹配，命中就停。这里有个细节：自动模式生效的前提是当前环境的类型必须与请求目标兼容。例如prod环境可以做只读性 API 的联调，但绝不该在上面对接写操作。所以我在环境定义里加了一个readonly: true/false标签，自动模式下凡是写操作命中只读环境，就直接拒绝转发并返回 403。

3.3 固定模式（Pinning）：防止意外漂移

第三种模式叫固定，我叫它"锁定某条规则不许动"。

举个例子：你在feat/order-0415分支上开发，自动模式把/api/order/*导到了env-order-test。但是这个环境今天下午挂了，你临时手动把/api/order/*切到了env-dev。此时如果不加锁定，下一次 git 分支切换触发自动规则更新时，你刚才的手动调整会被覆盖。

固定模式就是解决这个问题的：

envm pin /api/order --env dev-dev --ttl 4h

这条命令把/api/order这个前缀锁在dev-dev环境四个小时，期间无论分支怎么切换、自动规则怎么跑，这个路径的流量都不会动。TTL 到期后自动解锁，避免你隔天忘了还有一条幽灵规则。

三种模式配合用下来，我的实际感受是：自动模式处理 80% 的日常场景，手动模式应对临时调整，固定模式保住那些"不能漂移"的关键规则。这套机制不是一开始就设计这么完整的，是在实际使用中一点一点补出来的，后面第 5 节我会讲具体踩过的坑。

4. 落地使用：从零配置到团队共享的完整流程

好，前面讲了工具的原理，现在说一下实际怎么落地。我用一个真实项目的例子走一遍完整流程。

4.1 初始化项目：环境清单和代理规则

假设项目叫mall-admin，是一个电商后台前端项目。我先在项目根目录跑初始化命令：

envm init mall-admin

这条命令干了两件事：生成一个.envm/目录，并在里面放了两个文件——envs.yaml（环境清单）和routes.yaml（路由规则）。

routes.yaml长这样：

# routes.yaml routes: - rule: auth-api match: host: "[admin|api].mallexample.com" path_prefix: /api/auth target_env: dev-auth options: change_origin: true - rule: order-api match: host: "[admin|api].mallexample.com" path_prefix: /api/order target_env: dev-order options: change_origin: true - rule: fallback match: host: ".*.mallexample.com" path_prefix: / target_env: dev-remote options: change_origin: true

注意match.host用的是正则表达式。为什么要用正则而不是通配符？因为有时候一个项目会同时用到多个子域名，比如admin.example.com和api.example.com——如果用通配符就得写两条规则，用正则一条就搞定了。

4.2 接入现有开发服务器

EnvManage 有两种接入 dev server 的方式：中间件方式和独立代理端口方式。

中间件方式适合 Vite、Webpack、Express 这种有中间件机制的服务器。在 Vite 里这么配：

// vite.config.js import envm from '@envm/vite-plugin'; export default { plugins: [ envm({ configPath: './.envm', mode: 'auto' }) ] }

插件会在 dev server 内部插入一段中间件，把所有请求先经过 EnvManage 的路由引擎，再决定转发到哪里。这种方式的优势是链路短、延迟低，每次请求只多了一次内部的规则判断。

独立代理端口方式适合那些不方便改代码的场景。EnvManage 会启动一个独立的代理服务，监听在比如127.0.0.1:8899，你只要把 dev server 的代理指向这个端口就行。这种方式相当于在本地起了一个前置网关，侵入性最小。

4.3 与团队协作：配置即代码

配置文件的共享是这个项目能落地的关键。.envm/目录提交到 git，每个成员clone下来之后就拥有完整的环境清单和路由规则。

但每个人的本地环境不同，我引入了一个"覆盖机制"：.envm/local.env.yaml这个文件不入库，里面写个人本地的环境差异。例如你自己在 8080 端口跑了一个 mock 服务，那你就在本地覆盖文件里把env-local的主机改成127.0.0.1:8080。

# .gitignore .envm/local.env.yaml

这样团队成员合代码时，永远不会因为各自本地端口不一致而互相覆盖配置。实测下来，这一条对多人协作的体验提升非常大。

4.4 命令速查和实践小贴士

常用命令我已经整理成了一张给团队用的速查卡，放在内部 wiki 上：

特别提示：envm doctor一定要在配完规则后跑一遍。它会检测出路由规则之间的冲突（比如两条规则匹配到了同一个路径并且目标环境还不一致），以及环境清单里 host 重复定义的问题。这些靠人眼很难发现，但都是运行时会真实掉链子的隐患。

5. 实战中的问题和处理：这些坑文档里不会写

工具做到能用的程度不难，做到"长时间戳不出一堆 bug 打扰你开发"才叫真的完成。我在这个过程中踩了不少坑，挑几个最典型的讲讲。

5.1 浏览器缓存导致的"环境幻觉"

某个前端同事跟我反馈：明明envm use切到了 staging 环境，页面上的数据却还是 dev 环境的。我第一反应也是路由规则没生效，查了很久日志，发现代理转发完全正确，目标地址确实是 staging。

问题是浏览器缓存了 dev 环境的 JS 和 API 响应。特别是某些接口没设置Cache-Control响应头时，浏览器会做启发式缓存，你在代理层面切了环境，浏览器却直接把缓存内容吐给你，看起来就像"切了没生效"。

解决办法不能靠人手工强刷，我在 EnvManage 里加了一个功能：切换环境时自动在响应头里注入一条cache-control: no-store，而且只对 html 入口和 json 响应生效，避免干扰静态资源的长缓存策略。这个功能属于辅助性质，但如果你不主动做，团队里迟早会有人被这种"幽灵缓存"坑一上午。

5.2 请求头改写过头了，导致登录失效

还有一个让我印象深刻的坑。http-proxy默认会透传Host请求头，如果后端做的是多租户校验，Host不对，响应可能直接报 403 或者跳登录。

第一次接入时，我把所有转发请求的 Host 都改成了目标环境的域名，用changeOrigin: true。结果有些后端服务用的是内部网关地址，并不认外部域名；有些服务又要检查原始请求头里的Origin字段来校验 CSRF。改一个头导致另一处验证失败，又得回头调整。

后来我做的处理是：把"是否改写 Host、Origin、Referer"做成每个环境独立的选项，默认全关，需要哪个开哪个。并且提供一个规则，只有特定路径前缀才执行特定的头改写。这个灵活度在多团队共用一套环境时尤其重要，因为不同的后端网关对请求头的要求差异极大。

5.3 WebSocket 转发容易被忽略

前后端联调时用 WebSocket 的场景今天非常多（通知、IM、实时数据面板都需要）。但不少本地代理工具只做 HTTP 转发，WebSocket 一上来就断开。

EnvManage 的代理器选型时我就特意要求支持 WebSocket 升级协议的透传。实测需要注意，WebSocket 握手阶段的Origin头不能被改写，否则浏览器会拒绝连接（401），因为服务端通常会校验 Origin。我们的change_origin配置默认只作用于 HTTP 请求头，WebSocket 握手头单独做了白名单处理，只允许改写Host，保留Origin。

我把这个坑写出来，是想特别提醒：如果你的项目用到 WebSocket，买代理工具/写代理工具时一定要确认它能不能正确处理升级握手，而不是看 demo 只测 REST API。

5.4 多环境数据污染：从工具层面给出提示

多环境并行的最大麻烦不是技术上的，是数据上的。你上午在 dev 环境造了一堆测试订单，下午切到 staging 环境，一看订单列表发现是另一套数据——不是 bug，但极容易让人误判。

EnvManage 在 web 版控制台上给每个生效环境加了一个醒目的标签色和名称水印，并且在status命令里输出一行当前环境提示。这不算什么高深技术，但它真的有效降低了团队内部误操作的概率。人不是机器，用环境切换的高频操作里，一点点可视化提示能省下大量不必要的排查时间。

6. 配置与规则之外：日志、调试和可观测性怎么做

工具做出来之后，我发现一个重要事实：代理工具的核心其实不是代理本身，而是可观测性。一旦流量路径复杂了（本地、远端、固定规则、自动推断混在一起），你根本不知道某个请求为什么去了某个环境。如果没有日志，排查起来就是灾难。

我在 EnvManage 里加了完整的请求追踪日志。每条请求进来到出去，会记录以下几项：

envm logs命令可以实时查看，也可以用--filter env=dev-remote只过滤某个环境的日志。

在此基础上我还导出一个JSON Lines 格式的日志文件：/.envm/logs/. 后续可以接入 ELK 或者 Loki 这类日志平台，也可以写个小脚本做请求量的统计，比如"今天哪些路径被切到了生产环境"，方便排查潜在误操作。

我一直强调可观测性，原因很简单：代理工具一旦配置复杂起来，人脑就不可靠了。你必须让工具自己讲清楚它做了什么、为什么这么做，这才是真正的"可管理"，而不是靠配置文件和沉默的转发。

7. 后续演进：从单机代理到团队基础设施

做到这个阶段，EnvManage 已经不只是一个本地小工具了。它承载了我们团队内部所有前端项目的环境切换和代理转发规则。如果往后继续演进，我目前看到有两条路值得走。

第一，配置下发中心化。目前环境清单在 git 仓库里，靠每个人git pull同步。但环境地址的变更频率不低，如果某个环境挂了需要临时切备用地址，让所有人重新 pull 再重启 dev server，延迟太高。比较理想的做法是有一个中心配置服务，EnVManage 定期拉取远端环境清单，检测到变更后自动热更新本地的代理规则。团队内部缓存一份，中心节点挂了个别的也不影响本地继续跑。

第二，按请求内容动态路由。现在路由规则只基于 Host 和路径前缀，够用但不够智能。有些场景下，同一个接口在不同请求参数下应该走不同环境（比如模拟不同租户的数据隔离）。下一步可以支持基于请求头、Cookie，甚至基于 query string 里的特定字段做路由。这样"多环境"就不只是环境地址的区别，而是真正按业务维度做流量路由。

当然这些都是"以后再说"的事。作为工具本身，只要能稳定解决"多环境开发代理管理"这个日常痛点，就已经很有价值了。写这个项目最大的心得是：这种给开发者自己用的工具，功能可以少，但配置结构要清晰、运行时状态可见、切换路径要可控。做到这三点，团队才愿意在每天的工作流里持续使用它。