企业协作平台多环境部署与版本管理：dev/test/prod三套体系实践

干企业级协作平台的同学应该都有体会，一个项目从本地开发到测试验证再到生产上线，中间被环境问题、包版本对不上、配置串环境拖死的次数，远比业务逻辑本身多。iPolloWork 这套部署形态与版本管理方案，就是我在维护 iPolloWork（企业内部团队协作与任务编排平台）时沉淀下来的实践总结。说穿了就是三件事：dev 系列命令怎么设计、三级打包怎么落地、版本序列怎么和每个环境一一对应。这篇文章会把整套方案拆开讲，包括踩过的坑和调整记录，适合正在搭多环境开发流程、或者被“打包产物对不上版本”折磨的团队参考。

1. 部署形态拆解：dev、test、prod 三套环境的边界与取舍

1.1 为什么 iPolloWork 要分成三套环境

iPolloWork 内部用得比较重的几个场景包括团队任务看板、定时和触发式的自动化编排，以及对接工位现场的边缘设备。这些场景有一个共同点：任何一个环节出问题，影响面都是横向的。任务看板挂掉，整个部门协作停摆；自动化编排跑错数据，下游报表全是脏的；边缘设备误触，现场执行流程直接乱套。如果所有环境都混在一套里，开发和测试的每一次操作都可能污染生产数据，反过来生产故障也会打断日常开发。所以分环境不是锦上添花，而是必须。

但分环境也不意味着拍脑袋分三套就完了，关键是每套环境的“验证目标”要清楚。我的划分逻辑是这样：

• dev 环境解决“我写的这段代码能不能跑”的问题，核心是反馈速度，允许脏数据、允许 mock、允许随时重启。
• test 环境解决“这一批改动合在一起还能不能用”的问题，核心是接近真实，数据用脱敏加造数脚本生成，配置尽量和生产对齐。
• prod 环境解决“用户实际使用中稳不稳定”的问题，核心是稳定性，任何变更都要走发布流程，数据绝不乱动。

很多团队的分环境之所以失效，就是 dev 和 test 的边界模糊：dev 里接了真实 API，测试人员又直接在 dev 上验，最后 test 形同虚设。我后来把 dev 环境的 API 默认指向 mock 服务，只有显式加了--real-api才允许连真实测试服，这一步就逼着团队把 dev 和 test 的角色分开。

1.2 三套环境的资源划分与隔离策略

三套环境具体长什么样，我用一个表格把关键差异列出来，后面所有命令和打包脚本都是按这套划分来设计的。

除了资源规格，隔离策略更值得讲。网络层面我把三套环境放在不同网段，dev 用 5173 等开发端口，test 走内部测试网关，prod 只暴露 443 和必要端口。配置文件也做了完全隔离：.env.development、.env.test、.env.production三个文件不允许互相引用，pro 的密钥更不会出现在任何非 prod 配置文件里。密钥管理用的是独立的配置中心，部署时由命令脚本动态注入，而不是把生产密码写进仓库再手动复制，那样迟早要出事。

1.3 边缘设备接入时的部署细节

iPolloWork 有一块业务是对接工控机和摄像头，这部分的部署形态和平常的 Web 服务很不一样，核心在 Linux 设备节点上。比如工控机上插了 USB 转串口，系统里就会出现/dev/ttyUSB0；如果整块 NVMe 硬盘做了分区，第一个 NVMe 硬盘的第五个分区会显示为/dev/nvme0n1p5。很多新手会把“设备节点”和“挂载点”弄混，以为/dev/nvme0n1p5就可以直接当目录用。其实设备节点只是块设备的入口，要先格式化、再mount到一个目录，应用层才能读写。

实操中遇到最多的三类问题：

1. 权限不足：应用进程以非 root 用户跑，访问/dev/ttyUSB0报permission denied。我的习惯是写 udev 规则，把设备权限绑定到特定用户组，而不是直接给 777，避免安全隐患。
2. 头文件缺失：和 USB 设备做原生通信时，编译装 libusb 相关组件经常报缺头文件。Linux 上要单独装 dev 开发包，而不是只装运行库，这一步会卡在“装了半天还是找不到头文件”上，原因就是缺了-dev后缀的包。
3. 磁盘占满：日志和构建缓存把/dev/nvme0n1p5对应分区写满，服务开始诡异报错。我在部署脚本里固定写了一个df检查，使用率超过阈值直接告警，不等卡死才去查。

2. dev 系列命令：从本地一键启动到环境定向调试

2.1 dev 系列命令的设计初衷与整体结构

早期 iPolloWork 用的是 npm scripts 直接堆启动命令，后面越堆越乱，痛点非常典型：新来的同事要翻 README 才知道先启动哪个服务、环境变量靠人肉 export 提示符时不时串环境、启动前没人检查端口和依赖、报错千奇百怪。为了收敛复杂度，我做了一套统一入口的命令行工具iwork，基于 Node.js 和 commander 实现，把常用的开发、打包、版本操作全部收进来，整体结构如下。

iwork dev # 本地开发，默认 mock，反馈最快 iwork dev:test # 以 test 环境配置启动本地服务，联调用 iwork dev:prod # 以 prod 环境配置启动本地服务，仅诊断用 iwork build # 打当前分支默认包（即 dev 包） iwork build:test # 打 test 三级包 iwork build:prod # 打 prod 三级包 iwork version # 查看当前版本序列与制品信息

团队用惯了之后，不再需要理解每次启动背后有多少参数，所有复杂度都被压在命令内部。我特意保留了底层 npm scripts 的透传能力，需要临时看细节时可以带--dry-run打印实际执行的动作，既方便高级用户，又不影响普通开发者的日常操作。

2.2 三条 dev 命令逐个讲

先说iwork dev。它的核心流程是先检查本地端口 5173 和 3001 是否被占用，损坏的 node_modules 先提示修复；然后读取.env.development和.env.local，把 API 默认指向 mock 服务，最后执行vite启动。整个过程大概 3 秒，没有一步超过 10 秒。这个流程里最容易被忽略的是端口检查，我选择固定端口而不是让 vite 自动换端口，因为在多端联调时，自动换端口会导致“你永远不知道这次开在哪个端口”的混乱。

iwork dev:test和dev的差别在配置来源：读取.env.test，API 地址指向测试服的网关。它会多做一件事，对比本地代码版本和测试服当前运行版本，如果差异过大，会打出一个提示：“测试服版本较旧，联调结果可能不准”。这个提示看起来简单，实际帮我们避免了很多“明明改了一堆，测试却说现象没变”的扯皮。

iwork dev:prod默认是禁止一键执行的，必须显式带--allow-prod并且有运维角色授权码。开发机上连生产 API 调试，风险不在“读数据”，而在于误操作写脏生产数据，或者调试日志里夹带生产敏感信息。这个命令存在的唯一理由是线上故障时，需要快速用本地代码复现并定位请求链路。三条命令内部都会校验NODE_ENV不能被手动覆盖，并且启动后打印当前环境标识、API 地址和版本号，一眼就能看出“我现在在联调什么环境”。

2.3 vue3 vite dev 局域网打开空白的那个坑

这个坑我印象很深，前端用 Vue3 加 Vite 的时候，iwork dev起好后，开发机本机访问一切正常，但同一网段同事用浏览器输入http://192.168.x.x:5173打开，页面白屏，控制台没有任何明显报错。排查下来是 Vite 默认server.host只绑定127.0.0.1，局域网其他机器根本访问不到 dev server。解决办法是在vite.config.ts中把 host 设为0.0.0.0。

// vite.config.ts export default defineConfig({ server: { host: '0.0.0.0', // 让局域网可访问 port: 5173, }, });

改完 host 后还有第二层坑：有些机器能打开页面，但接口请求全部失败。原因是浏览器访问的是 IP，而代码里的 apiBase 还是http://localhost:3001，跨域和指向错误一起出现。后来我在iwork dev里做了两件事：一是根据访问来源自动计算当前机器 IP 并注入到环境变量，二是让 vite 代理/api前缀到实际后端端口，避免写死localhost。另外一定要检查防火墙，测试机上如果是云厂商安全组或者本地 ufw 拦了 5173，照样白屏。iwork dev:test里我加了一个“局域网健康检查”，启动后主动请求一次http://<本机IP>:5173，能通才提示成功，避免部署后再绕一大圈。

3. 三级打包体系：dev包、test包、prod包的分级产物

3.1 为什么是“三级”而不是一包打天下

有人会问，既然代码是同一份，为什么不直接打一个包，到不同环境用不同配置运行？理论上可以，但在 iPolloWork 这种对接边缘设备、有自动化编排任务的项目里，实际执行时差异太大。首先，现场诊断问题需要 dev 包能带 sourcemap、完整日志和调试探针，但 prod 包如果也带这些，等于给攻击者送源码，日志量还会把磁盘打爆。其次，API 地址、上报开关、安全策略在不同阶段完全不同，与其在运行时动态判断，不如在打包时就固定每种环境的基线。最后，设备端脚本和固件部署常常是离线的，无法依赖“到环境再去拉配置”，打包时必须把所有环境相关的东西都塞进产物里。

所以我把打包标准定为：同一个源码，同一套脚本，产出三种可独立部署的产物。每种产物从一开始就决定了自己属于哪个环境，不允许一个包到处部署。这个约束在发布流程里自动执行，人为给测试环境装 prod 包的情况几乎消失了。

3.2 三级打包的命令与产物差异

三级打包通过三条命令完成，iwork build等价于iwork build:dev。

iwork build # 等价于 iwork build:dev，产出 dev 包 iwork build:test # 产出 test 包 iwork build:prod # 产出 prod 包

产物名称和差异统一用下面这个表管理：

命名里我特意把环境名放在版本号前面，这样一眼就能看出制品属于哪个环境。每个包都会附带一个manifest.json产物清单和一份 sha256 校验文件，部署前先校验 hash，能挡住很多“文件传错环境”的低级问题。manifest.json里记录的信息包括版本号、环境、git commit、构建时间、产物 hash、依赖锁定版本，部署时先看它再动服务，已经成为团队默认动作。

3.3 打包脚本中的关键细节：环境注入与产物清单

打包脚本核心部分用 Node.js 写，逻辑不复杂，但有几个细节必须强调。第一是环境注入：在构建之前，脚本会检查当前是否通过iwork进入，禁止裸用vite build，防止有人跳过环境基线。第二是产物命名和清单文件生成。构建完成后，脚本会把产物复制到制品目录并统一命名，再生成清单，例如：

{ "scripts": { "build": "node scripts/build.mjs", "build:test": "iwork build:test", "build:prod": "iwork build:prod" } }

制品库保留策略也很有讲究：dev 包保留最近 10 个、test 包保留最近 30 个、prod 包每个版本永久保留。这个策略避免了一个现实问题：环境反复回滚时找不到之前的包，或者包库里堆满过期 dev 包。打包时会输出一条构建摘要，包括产物路径、大小和 hash，我用终端里格式化好的信息来做发布记录，比看仓库 commit 直观得多。

4. 版本序列管理：语义化版本与构建号的双轨协同

4.1 版本序列的组成规则

版本管理的核心诉求是：在任何时候、任何环境上，都能回答“我当前跑的是哪个版本、对应哪次提交、构建于什么时间”。单靠语义化版本不够，因为1.2.3可能被人为改过。我的做法是双轨制，把可读版本号和机器构建号放在同一个版本序列里。

典型版本序列长这样：

1.2.3-beta.1+build.20240610.1700

拆开看：主版本号 1、次版本号 2、修订号 3 是语义化版本，表示功能级别；-beta.1是预发布标签，表示还没到正式发布水准；+build.20240610.1700是构建号，包含日期时间，机器可以精确识别是哪一次构建，抗重复和抗迷惑能力比单纯加序号强。正式发布时去掉-beta后缀，只保留1.2.3+build.20240610.1700。

为什么会想到加构建号？因为出现过一个事故：测试环境和生产环境的包版本都显示1.2.3，但行为完全不一样。查了很久发现测试服务器上其实是两天前某个中间版本编译的包，只是有人手动把版本号改回了1.2.3。加构建号之后，版本里天然带着时间戳，想瞒都瞒不住。

4.2 版本号自动递增的落地方式

手动改版本号注定会漏，我把递增逻辑交给了 CI。每次合并代码到主干或发布分支时，流水线跑一个版本计算脚本，按以下规则决定下一个版本号：

• fix:开头的提交 → 修订号 +1，如1.2.3→1.2.4
• feat:开头的提交 → 次版本号 +1，修订号归零，如1.2.3→1.3.0
• 带BREAKING CHANGE的提交 → 主版本号 +1，次版本和修订号归零，如1.2.3→2.0.0
• 预发布分支的提交 → 在目标版本后面追加-beta.N，N 随提交次数递增

这个规则本质上是把 Conventional Commits 和语义化版本打通了，好处是团队不需要有人专门负责“想”版本号，坏处是要求提交信息必须规范。所以 CI 里加了一个提交信息 lint，不合规直接拦下，拦几次之后大家就都习惯了。还有一个细节：CI 计算出的版本号必须写入构建产物，写进manifest.json和包内version文件，而不是只存在于流水线日志里。只有写入制品，版本才能伴随部署链路走到底。

4.3 版本、制品、环境配置三者的映射关系

版本序列最终要落到“同一个版本号，不同环境到底跑的是什么”。我用一个映射表来管理：

核心原则是：环境差异只来自配置文件，不来自代码分支。dev、test、prod 共用同一套源码，只是不同环境的配置注入不同。这样“版本对不上”的问题就变成“你拿到的制品和配置是不是一对儿”。为了验证这个映射，发布脚本会在部署后主动读取/api/version接口，返回当前版本号与构建时间，和部署计划比对，不一致直接告警，不让问题沉淀到用户侧。

5. 常见问题与排查技巧实录

5.1 dev 环境反复出现的三类故障

de 环境用久了，最常见的是这三类。

第一类是端口被占。5173 被其他 vite 进程占用时，iwork dev会直接检测并提示，而不是让 vite 自动换端口。自动换端口在联调时反而制造混乱，因为你永远不知道这次开在哪个端口。我选择固定端口，冲突就直接清理掉旧的进程，宁可多一步操作也要保证环境可预期。

第二类是依赖不完整。node_modules 缺失或半装的概率很高，尤其是有人用npm ci执行到一半取消的时候。启动前检查不是万能的，但至少能在报错之前给出“执行pnpm install修复”的明确提示，而不是抛一段吞吞吐吐的模块找不到报错。检查机制很简单，比对 lock 文件和 node_modules 里的版本记录，不一致就拦下。

第三类是局域网白屏。这个在上文完整讲过，核心点再强调一遍：host 设置为0.0.0.0、代理别写死 localhost、检查防火墙。排查的时候我习惯先看进程和端口，再看环境变量，最后才看代码，顺序反了很容易浪费时间。

5.2 打包产物与版本号对不上

这个问题的根因通常是 CI 缓存和本地手工打包混着用。典型场景是开发者在本地打了iwork build:test推到制品库，但本地没有最新 tag，于是产物里的 git commit 是旧的，版本号却是新的，部署到测试环境后功能表现和预期不符。排查时第一步看manifest.json里的 commit 时间，第二步对比 git log，问题立刻现形。

我的对策是：禁止本地手工打 test 和 prod 包，只允许 CI 触发。如果需要快速验证，就推一个带[build]标记的提交，CI 打完自动通知。20 分钟等待换来的是一致性，值得。可能有人觉得这条规则太硬，但经历过一次“本地环境能跑、测试环境挂了”的争论之后，团队就会明白统一构建来源的价值。

5.3 配置串环境与磁盘占满

配置串环境是另一个高频坑，本质是NODE_ENV和自定义的ENV变量搞混了，导致配置加载到错误环境。典型事故：某次测试环境重启后，服务竟然连上了生产数据库，原因就是有人把.env.production的数据库地址复制到了.env.test下，同名变量被测试环境加载。解法分两层：代码层启动时检查当前ENV和目标配置文件是否匹配，流程层把配置文件纳入版本管理，禁止手动复制，环境标识写在文件名和内容头部双重确认。

磁盘占满和边缘设备部署时提到的/dev/nvme0n1p5分区有关。日志和构建缓存是最常见的占满来源。我在部署脚本里加了预检：

df -h /dev/nvme0n1p5 # 使用率高于 85% 时自动告警并停止构建

配一个告警脚本成本极低，但能避免“凌晨磁盘满导致服务崩溃”这种最困的故障。实际上真正让分区爆掉的一般是大量调试日志和旧构建产物，所以我还写了一个定时清理任务，保留最近多少 GB 即可，超过部分按时长分批清掉，既不影响排障，也不会让磁盘无限上涨。

6. 最后一点经验

这套部署形态与版本管理跑了将近半年，我最直观的体会是：版本序列一旦能可靠地回答“某个环境上跑的是哪个版本、对应哪次提交、构建于什么时间”，跨团队扯皮的次数会断崖式下降。以前测试和生产说“现象不一样”，要靠人肉对齐才能定位分歧，现在直接对manifest.json和/api/version返回值就行。

最后再分享一个小技巧：把iwork version的结果打印在登录页或者管理后台的角落，性价比极高。运维、测试、开发每天打开系统都能看到版本号，很多环境误判在第一步就被消掉了。这套方案后续还可以扩展成自动发布流水线：三级打包产出后由 CI 直接推到对应环境，版本序列再往上游接工单系统，做成“需求 → 版本 → 制品 → 环境”的全链路追踪，那基本就是发布工程化的完整体了。