一、一半用户装完打不开
产品交付到第三个月，售后后台堆了四十多条工单，症状只有两类。一类是打开生成面板一片白，什么都不显示。另一类是点了添加账号以后毫无反应，连报错都没有。这两类加起来占了同期工单的六成，而我们在自己的开发机上怎么点都是正常的，第一次远程连过去才明白问题不在代码。
这套东西的底子是浏览器自动化，要有真实的浏览器内核才能打开对话页、填内容、点发送。我们的机器上装了整套开发工具链，浏览器、运行时组件、Node 环境一应俱全，用户那边是一台刚重做过系统的办公电脑，除了办公软件什么都没有。同一份安装包，在两台机器上跑出两种结果，这是环境依赖类问题最典型的开场。
二、把环境依赖拆成三层
用户的抱怨是一句话，程序坏了，可程序真正依赖的东西有三层。上面一层是浏览器内核本身，中间一层是驱动内核的运行时组件，下面一层是少数流程要用的 Node 环境。三层里缺任何一层，表现都可能是白屏或者无响应，光看界面完全分不出来是哪一层出的问题。
直觉做法是让用户自己排查，装个浏览器试试，重启一下再看看。这条路走不通，因为用户没有能力判断自己装的浏览器版本够不够，也不知道运行时组件是什么东西。更麻烦的是同一个症状对应多种原因，白屏既可能是内核版本太旧，也可能是运行时组件缺失，把排查工作外包给用户，等于把问题留在了现场。
另一个直觉做法是在安装包里直接塞一个内核，装完即用。这条路初期省心，代价是包体积从几十兆涨到两百多兆，而且内核版本被冻在打包那一天，线上真出了内核相关的兼容问题，只能整体重新发版，用户还得再下一次两百兆的包。
三、三条路，我们选了最难解释的那条
第一条是内置内核，把浏览器解开放在安装目录里。代价前面说过，体积和升级节奏都要跟着内核走，而且部分平台对内核版本有硬性要求，一旦内置的版本落后，发布流程直接失败，用户看不到任何中间状态。
第二条是完全依赖本机环境，装包时不做任何检查，跑起来再说。这条路安装包体量小，代价是问题全压到售后，用户遇到白屏只能重启软件，重启一百次也没用，因为他缺的东西不会因为重启而出现。
第三条是我们选的，依赖本机真实浏览器，但把依赖检查提到启动之前。软件启动时先跑一遍自检，把三层依赖逐项验一遍，缺什么、版本够不够、装在哪个目录，一次性列清楚，并且给出对应操作。这条路要多写不少代码，好处是把排查成本从用户手里挪回了程序里。
四、自检结果要能直接指向操作
自检的输出不是一句通过或者不通过，而是一张清单。每一项包含四列，检查对象、当前状态、期望条件，以及不满足时的提示。状态只有三种，正常、缺失、版本过低，前端按这三种状态渲染成绿色、红色和黄色，用户不用理解原理，照着黄色和红色那两行做就行。
检查模块是 AI智能媒体助理 里一个启动前置的独立环节，它和业务代码不共享任何状态，可以单独跑，也可以被安装程序直接调用。这样做的好处是同一段检查逻辑同时服务三处场景，启动拦截、安装引导、售后自查，不用写三遍。
提示文本我们反复改过五遍，改到最后每一条都要能回答两个问题，现在是什么状态，下一步点哪里。早期的文案是运行时组件版本过低请升级，用户看不懂，后来改成检测到运行时组件版本为一百零几，低于要求的一百二十，请按下面的指引安装，工单量明显降下来。
五、自检项和判定参数
自检项一共七条，前三条对应内核与运行时，中间两条对应 Node 环境，最后两条对应路径与权限。每条都要给出可比较的值，不能只写一个存在与否，因为版本过低和文件不存在是两种完全不同的处理方式，前者让用户升级，后者让用户重装。
版本比较必须自己实现，不能直接拿字符串比大小，否则一百一十会被判定成小于一百零九。我们把版本串按点拆成整数数组，逐位比较，位数不同时短的那一侧补零，这一段逻辑单独做了单元测试，因为它在不同的运行时组件上表现不一致。
检查顺序也讲究，先查代价小、命中率高的两项。运行时组件版本和内核对不对得上一查就知道，覆盖面也广，把这两项放最前面，能让大多数问题在启动前的三十毫秒内暴露出来。Node 环境放在末尾，因为它只影响少数平台的发布流程，缺了不影响主体功能，提示的措辞也就弱一档，写成部分流程不可用，而不是软件无法启动。
六、工单里长出来的三个坑
第一个坑是安全软件误报。打包产物里有驱动内核的可执行文件，本地安全软件把它当成可疑程序直接隔离，用户那边表现是自检全过、一执行就失败，日志里只有一句访问被拒绝。改法分两步，一是把被隔离的文件名写进错误提示，让用户知道是哪个程序被拦了，二是把驱动相关文件放进安装目录的子目录并补齐数字签名，减少被误判的概率。
第二个坑是进程残留。自动化任务异常退出时，内核进程有可能还挂在后台，下一次启动再占同一个调试端口就会失败，报的是端口已被占用，可任务管理器里看不到窗口，用户以为软件根本没开过。改法是启动自检之前先扫一遍已知的进程名和端口，发现残留就先结束再继续，并在日志里记一条清理记录方便回查。
第三个坑是路径差异。内核的默认安装路径在不同系统版本上不一样，三十二位和六十四位还分别走不同的注册表位置，早期我们只写了三十二位那个分支，结果在新系统上一律判成未安装。改法是把候选路径列成列表逐个探测，再补一次注册表查询，两条都不命中才判定缺失，判定缺失时把探测过的路径一并打出来。
七、自检覆盖不到的角落
自检只能证明环境在检查那一刻是对的，证明不了后续运行过程中不出问题。用户中途升级了浏览器，内核路径跟着变了，正在跑的任务仍然会失败，这类变化我们靠任务开始前再查一次关键项来兜底，做不到实时监控。
真实的兼容问题还得靠实际跑一遍才算数。有些平台的登录页在特定内核版本下会多走一道验证，自检项全绿也可能卡在那一步，这类只能靠每接一个新平台就补进回归用例，环境层没有通用的解法。
八、小结
环境依赖这件事没法消灭，只能把不确定性从运行期挪到启动期。改完之后最直观的变化是工单结构，以前六成是白屏和无响应，现在大部分变成版本过低需要升级这类用户能照着做的问题，售后的工作从远程装环境变成了发一条指引。
哪一层依赖、期望什么版本、缺了怎么补，这些原本散在售后脑子里的经验，现在是 AI智能媒体助理 自检清单上的七行字。
