先说一个真实场景。某次线上启动白屏排查业务侧转给我一份日志里面只有一行Check.js: Assertion Failed.。我盯着这行日志愣了几秒——Check.js是哪个文件沿着仓库路径找进去Source/Core/Check.js安安静静躺在所有业务模块的最底层将近八百行代码没有UI不处理事件只向外抛一个异步函数。当时我最大的感受不是“这文件写得多好”而是“这东西怎么变成线上事故源头的”。后来仔细翻了它的实现、调用链和周围配套代码才真正意识到一个核心目录下的Check类模块表面上是启动前的一堆if判断实际上承担的是应用生命周期的第一道闸门。它的水有多深不拆开看永远不知道。这篇文章就围绕Source/Core/Check.js这类“核心检查模块”来讲。无论你是在React Native、小程序还是纯前端项目里维护类似文件下面的设计逻辑、坑点和排查路径应该都能对得上号。也给正准备重构这类模块的人一个参考检查逻辑要怎么组织才不会从守卫者变成事故制造者。1. 一个藏在核心目录里的守卫者Check.js在项目里到底扮演什么角色1.1 从目录路径反推架构层级source/core意味着什么像Source/Core/Check.js这样的路径第一眼信息量就很大。Source说明它在应用源码内不是第三方依赖Core说明它处于基础层不是页面模块也不是业务组件Check.js这个文件名则直接暴露了它的职能——负责“检查确认”。在我维护的项目里这类目录往往位于依赖图的最底层。App启动时入口文件会先加载Core下的初始化模块再逐层往上注册业务模块。Check.js就处于这条链路的咽喉位置它先于绝大多数业务代码执行如果在它里面抛异常后面所有模块都不会初始化。反过来说也正因为处在咽喉位置它最容易犯的错就是“管太宽”。我见过不少类似的check文件越改越臃肿慢慢把环境判断、权限申请、配置拉取、业务开关甚至埋点初始化全塞进去最后谁都不敢动它——一动就崩崩了也不知道是哪段检查逻辑引发的问题。所以接手这类文件的第一步不是看代码而是先和团队对齐职责边界Check.js只负责把环境、依赖、前置条件状态问清楚并且给出一个清晰结论。它不该去执行修复动作不该自己拉配置、写缓存、弹提示更不应该直接改变业务模块的挂载逻辑。1.2 Check.js在启动链路里的位置与行为契约拿一次典型启动过程来说大致的调用顺序是这样的应用入口初始化基础配置然后调用runCoreChecks()拿到所有检查结果再根据结果决定要不要继续加载核心模块和业务模块。Check.js在中间承担的是“断言者”角色它会告诉你三件事当前运行环境是否满足最低要求核心依赖是否都齐了有没有哪一项属于“继续跑也白跑”的致命问题。我们项目里这个文件的核心导出函数签名很简单只做一件事执行一组预置检查项聚合结果后返回。返回值是一个结构化对象包含passed、level、errors、warnings这些字段后续模块根据它来决定启动策略。提示核心Check模块一定要保持“无副作用”的调用方式。一个简单的标准是——同一个环境下调用十次和调用一次结果应该完全一致。如果做不到说明检查代码里混入了状态修改或数据拉取逻辑迟早要出事。2. 一个真实Check.js最常检查的四类问题从环境到业务前置条件2.1 运行环境自检平台、容器、权限的能级探测第一类检查项是对运行环境做“能级探测”。拿跨端项目来说最常见的是判断当前平台和容器版本是否支持核心功能。例如某个能力依赖原生端新加的接口但用户装的客户端版本太老接口不存在。Check.js要做的就是提前发现这种情况别等业务代码调用时才抛一个看不懂的TypeError。这类检查的常见例子有当前平台是iOS还是Android版本号是否达到最低要求WebView环境是否可用容器桥是否注入成功摄像头、定位、通知等权限状态是否处于预期值当前网络类型是否支持某些核心链路比如必须Wi-Fi才能预加载的资源。要注意这里有个关键细节权限检查要区分“未授权”和“用户还没决定”。很多check文件会直接把not determined当成失败处理结果弹出一堆权限请求体验非常糟糕。判断一个环境检查项是否合理可以这样问自己如果这一项不通过后续代码是不是一定跑不起来如果不是一定跑不起来它就不该是fatal级别只能算警告或者干脆只做记录。2.2 模块依赖与配置完整性原生桥、特性开关、远程配置第二类检查项是“依赖清单核对”。现代前端项目很少只有一个JS运行时React Native要依赖原生桥小程序要依赖平台注入的全局对象H5项目要依赖运行时挂载的一些SDK实例。这些依赖只要有缺失后续调用基本都会白屏。Check.js在这里要通过清单校验以下内容原生模块是否都完成了注册关键native bridge方法是否为函数核心配置文件是否完整必要的启动参数有没有在入口处注入远程配置/feature toggle服务是否已就绪如果未就绪降级策略是什么本地缓存数据目录是否可写磁盘空间是否低于警戒线。这个场景下我一直推荐用“白名单清单”而不是“逐个手写if”。把语法从if (typeof xx undefined) throw Error(xx is missing)改成一张配置表既好维护又能自动生成缺失项报告。2.3 业务前置条件登录态、版本准入与灰度范围第三类检查会带一点业务属性。很多人会问核心层的Check.js不该只做技术检查吗为什么还要管登录态道理很简单有些业务模块在未登录状态下启动会拉取一堆注定失败的用户数据请求既浪费流量又拖慢启动。较合理的做法是把登录态检查挪到对应的业务域启动器里而不是放进Core层。Core层的Check.js只处理那些“影响整体启动方向”的业务前置条件例如最低启动版本号接口已经强制下线旧版本客户端必须弹更新当前账号是否被列入功能黑名单/体验白名单直接影响默认模块展示本次启动的渠道来源如分享唤起、扫码唤起决定需要加载的业务包不同。这类业务判断放进Core层要格外谨慎。最好的方式是给Check.js预留一个customChecks接入点让业务侧传入自己需要的前置条件核心文件本身不写死任何业务逻辑。2.4 三种检查结果语义fatal、warn与silent如何决定启动走向把检查结果分成三档是让Check.js变清晰的关键一步。fatal致命问题直接阻断启动流程并给出用户可理解的错误提示或恢复指引。比如容器桥未注入后续所有native调用都会失败这时继续启动没有意义。warn非致命问题允许继续启动但要记录warning并走降级逻辑。比如某个非核心SDK初始化失败可以先跑主流程待会儿再重试。silent静默探知问题结果只写入内部日志或指标不做任何展示也不影响启动流程。例如启动时探测某API在当前设备上是否存在为后续功能决策提供参数。大部分Check类模块写不好的原因是把所有问题都当成fatal处理。结果就是线上环境稍微有点风吹草动用户就一片白屏而真正致命的问题反而被淹没在大量警告里难以被发现。3. 组织核心启动检查代码时避免把Check.js写成违章建筑3.1 检查清单化用数据和规则替代无限if else一个800行的Check.js如果全部由手写if组成读起来会是灾难。有人会觉得核心模块能跑就行但维护过的人都知道真正出问题时你根本不敢确认某段逻辑到底覆盖了哪些分支。我后来把这块代码重构成了“清单执行器”模式。每个检查项都是结构化数据有名字、级别、执行函数const checkItems [ { name: env-basic, level: fatal, run: (ctx) checkEnvironment(ctx), }, { name: native-bridge, level: fatal, run: (ctx) checkNativeBridge(ctx), }, { name: remote-config, level: warn, run: (ctx) checkRemoteConfig(ctx), }, { name: permission-location, level: warn, run: (ctx) checkLocationPermission(ctx), }, ]; async function runCoreChecks(ctx) { const results []; for (const item of checkItems) { const start Date.now(); try { const outcome await item.run(ctx); results.push({ name: item.name, level: item.level, passed: outcome.passed, ...outcome.detail, }); } catch (err) { results.push({ name: item.name, level: item.level, passed: false, code: CHECK_INTERNAL_ERROR, message: err.message, }); } finally { // record duration in ctx.metrics } } return summarize(results); }清单化之后新增一个检查项不用去理解整段启动逻辑只需要在数组中加一条写好自己的run函数就行。同时查看所有检查项的范围、级别、责任边界也变得一目了然。3.2 返回值设计code/message/meta分开放弃纯布尔流很多失败日志难排查问题出在检查结果只返回了一个布尔值或一段人话。false能说明“没通过”但它没说明为什么没通过、是哪类问题、该找谁修。我习惯给每个结果设计这样几个字段code稳定的错误码用于日志检索、上报归类和自动化测试断言message面向开发者的可读描述说明具体缺了什么、当前值是什么meta附加数据例如当前版本号、期望版本号、相关模块名方便定位level严重级别调用方可以根据其决定是否阻断。这样设计有个直观好处看日志时不再是翻聊天记录一样的散文而是直接能通过code查到同类问题历史上出现过多少次。3.3 执行顺序、并发窗口与超时控制检查项的编排需要特别注意顺序问题。有些检查彼此之间有依赖关系比如“网络能力是否可用”依赖于“配置表是否完成初始化”。如果并行乱跑可能先测网络时配置还没到位导致误报故障。我们目前把检查任务分成两段处理第一段必须串行只做最核心的依赖校验容器、主配置、原生桥顺序固定第二段可以并发跑剩余的非关键探测不阻塞首屏关键路径。超时控制也是重点。检查模块如果忘记设置超时一旦某个底层API进入挂起状态整个启动链路都会被卡死。我曾经处理过一个问题——某个探测插件在特殊网络环境下永不回调前端设置了三秒超时兜底线上问题才真正被隔离。3.4 错误分类让上层能分清环境问题还是配置问题Check模块返回的Error如果不做分类上层只能采用“一刀切”策略要么全部弹窗要么全部静默。常见的分类方式如下错误类型代表场景建议处理EnvironmentError平台版本不满足、API不支持提示升级或更换设备DependencyError原生桥缺失、SDK未注入提示重启App或检查集成配置ConfigError启动配置缺失、字段类型不符提示联系管理员并给错误码PermissionError权限未授予、用户拒绝引导进入系统设置页NetworkError网络探测异常、域名不可达友好提示稍后重试有了这些分类上层组件就能给出更精准的兜底UI而不是所有错误都渲染一个通用错误页。4. 一次Check.js误伤线上环境的完整排查链路4.1 现象与第一反应那次线上事故现象是小范围用户启动App后出现白屏。代码回滚到上一版本能恢复正常说明问题出在新版本代码。但奇怪的是我的本地开发环境、测试设备、模拟器上全部复现不了。一开始的直觉是“网络配置或接口兼容问题”但翻监控发现接口请求根本没发出去。接着怀疑“某个第三方SDK崩了”查崩溃日志也没有新增崩溃点位。最后还是业务侧提供了一条关键日志——Check.js: Assertion Failed: device.apiLevel not supported。看到这条日志的瞬间我意识到问题出在核心检查逻辑上它把一个环境探测结果拦住了导致后续模块压根没被加载。4.2 从日志反查检查项的根因那条错误日志来自新增的一个“能力探测”检查项。代码大概是这样的简化版const apiResult await probeDeviceCapability(); if (!apiResult.isSupported) { return { passed: false, level: fatal, code: DEVICE_API_NOT_SUPPORTED }; }问题出在probeDeviceCapability()这个函数它内部调用了某个新版本才提供的探测接口在较老系统上这个接口不存在于是函数内部抛了TypeError。外层虽然有try/catch但catch逻辑一律默认返回“不支持”而不区分“这是探测失败”还是“探测后确认不可用”。所以线上那些用户未必真的不支持新功能只是探针本身在它们的环境里坏了结果却被当成fatal处理把整个App启动堵死了。这种问题之所以本地测不出来是因为我的测试机系统版本够新probeDeviceCapability()走的是一条完全正常的路径。而报错用户大多集中在System WebView版本较旧的设备上。4.3 修复方案与沉淀出的规范修复其实不复杂把状态从二元改成三元。引入unknown状态并给探测接口加上超时保护。当探测抛异常或超时时不能直接当成“不支持”而是进入降级逻辑——宁可保守放行让业务层再兜底也不要错误阻断启动。修复后的判断逻辑变为确认支持返回通过确认不支持返回ConfigError并给提示探测失败或超时返回warn级别的unknown状态按“假阳性放行”处理并上报日志。我们在这次事故里提炼出了三条规范。第一能力探测类检查必须有超时控制和异常捕获第二“探测失败”和“确认不支持”决不能混为一谈第三所有引用全局对象或第三方扩展对象的地方访问前必须判断对象是否存在。后来这条规范被写进了团队的代码评审清单Check.js再新增检查项时这三条是被点名的必查项。注意核心检查模块是启动链路的闸门。闸门不怕“漏过个别问题”最怕“误关整条链路”。在不确定时优先fail-open而不是fail-closed是非常实用的运维经验。5. 让Check.js持续可维护测试与可观测性的配套设计5.1 把外部能力变成可注入依赖Check模块难测试的根源在于直接依赖了平台API、原生桥、全局配置。单测环境里这些能力往往不存在导致测试用例要么跳过要么只能测正常分支。更合适的方式是依赖注入。Check.js不直接去拿window、global或某个原生模块而是通过外部传入的ctx对象访问所有外部能力。这个ctx可以是真实的运行时上下文也可以是由测试代码构造的mock对象。具体做法是把每个检查项的run函数设计成纯函数只依赖参数不依赖模块作用域。这样单测里可以自由控制环境变量const ctx buildTestContext({ platform: android, sdkVersion: 23, nativeBridge: { isReady: false }, }); const result await checkItems[1].run(ctx); expect(result.passed).toBe(false); expect(result.code).toBe(NATIVE_BRIDGE_NOT_READY);依赖注入还能带来一个额外收益代码评审时能清楚地看到每个检查项到底“碰了哪些外部依赖”哪些是合理访问哪些是越权访问。5.2 为检查项设计的单元测试打法Checks清单本身就是天然的结构化测试单元。我比较推荐的做法是“一查一项一用例文件”。针对每条check准备三类测试正常通过场景所有依赖满足返回passed为true缺依赖场景某一个前置条件不满足返回预期的错误码和等级抛异常场景外部能力本身抛错确保被catch并转换成稳定结构。四年前我重构这类模块时靠这种方法把核心检查的测试覆盖率从20%提到了90%左右。更要紧的是它让后续新增检查项有了可参照的代码范本而不是靠老一辈同事逐行解释“这个地方原来为什么这么写”。5.3 统一日志与外层性能打点Check.js是启动关键路径的一部分所以日志和组织要尽量工程化。日志输出统一采用[CoreCheck]前缀加结构化字段格式至少包含以下信息检查项名称name检查结果passed/failed严重级别level错误码code该检查项耗时duration关键上下文例如平台版本、配置版本。有了统一格式后写排查脚本会非常顺利。举个例子在排查某次“部分用户启动卡住”的问题时我只用了一行grep命令就把所有耗时超过500ms的检查项筛了出来问题定位直接收敛到了某个网络探测项前后不到十分钟。性能打点也很关键。Check.js本身是启动流程的一部分它的耗时直接贡献了首屏时间指标。我会在check入口处记录整体启动检查耗时并分别统计每个内部项执行了多少毫秒方便后续优化。5.4 启动通过率指标与告警最后是观测体系的收口。光在本地日志里记录还不够要把核心检查的通过率作为持续的客观衡量指标。在客户端的启动链路结束时上报一次字段包括是否成功进入首页、是否出现fatal级检查失败、失败的错误码是什么。有了这些数据后可以让质量监控系统在“启动通过率下降”时发出高风险告警。很多启动类故障如果等到用户投诉才被发现就已经太晚了而检查模块本身就有日志将这些日志数据经过处理变成线上看板上的关键指标会让维护工作从被动响应变成主动防御。6. 渐进式检查尽可能让Check.js甩掉“启动变慢”这口锅6.1 启动前必须做的检查越少越好一听到“核心检查”这个词很多人下意识会把所有想确认的逻辑全塞到启动时。这是导致启动变慢的直接原因也是Check.js慢慢变成人人喊打模块的根源。要解决的思路不是“不做检查”而是“在正确的时机做”。启动前只保留那些“不做就无法启动”的检查项可在运行中检查的挪到后台可延迟到使用具体功能前再检查的就放到功能入口。例如权限请求完全没必要在启动时全部检查只有进入对应功能时才去触发授权状态判断这才是更合理的产品体验。6.2 把检查结果自动转成工单或看板Check.js不应该只是一个“启动器内部函数”它的结果完全可以走得更远。一种很实用的做法是把fatal级别的检查失败记录到质量统计平台并且根据错误码自动归集到对应负责团队。比如归属于原生基础能力的DependencyError落到客户端基础组ConfigError落到服务端配置组PermissionError则更多地进入用户体验专项分析。这样核心Check模块就成了团队协作的一根探针让各个问题在发生后的第一时间找到归属而不是全部积压在几个研发手里等人肉分配。6.3 留给未来维护者的纪律如果非要给后来维护这类模块的人一句忠告我会说把Check.js当核心基础设施对待而不是当普通工具文件。它值得拥有独立的代码评审规则、更严格的测试覆盖和更清晰的架构边界。建议团队里约定以下纪律新增检查项必须走清单注册制不允许在文件顶部或导出函数里随手加裸if修改已有检查项的level必须经过评审防止有人为了让自己负责的模块不被拦截而把fatal降级成warn每次改动都需要跑全量check单元测试保证结果数据结构稳定禁止在此模块中直接调用业务组件或访问页面级对象。还有一个小技巧在文件顶部用注释写明这个模块的职责边界和所有terms的定义。比如什么才算fatal什么才算warn错误码前缀的命名规范等。这份注释看起来简单却能大幅减少后来者和早期设计者之间的认知偏差。如果正在为你触手可及的Check.js头疼建议先做三件事梳理它到底在检查什么给每个检查项明确级别和错误码把外部依赖全部注入改写一遍。做完这三步很多说不清楚的问题大概都会在整理的过程中露出水面。我自己的经验是所谓核心类的模块维护最重要的事情不是“写得有多巧妙”而是“让每一个后来者都能在半小时之内搞懂规则放心的动手改”。