剖析核心检查模块Check.js：启动白屏治理与前端架构设计

先说一个真实场景。某次线上启动白屏排查，业务侧转给我一份日志，里面只有一行：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 执行顺序、并发窗口与超时控制

检查项的编排需要特别注意顺序问题。有些检查彼此之间有依赖关系，比如“网络能力是否可用”依赖于“配置表是否完成初始化”。如果并行乱跑，可能先测网络时配置还没到位，导致误报故障。

我们目前把检查任务分成两段处理：

1. 第一段必须串行，只做最核心的依赖校验（容器、主配置、原生桥），顺序固定；
2. 第二段可以并发，跑剩余的非关键探测，不阻塞首屏关键路径。

超时控制也是重点。检查模块如果忘记设置超时，一旦某个底层API进入挂起状态，整个启动链路都会被卡死。我曾经处理过一个问题——某个探测插件在特殊网络环境下永不回调，前端设置了三秒超时兜底，线上问题才真正被隔离。

3.4 错误分类：让上层能分清环境问题还是配置问题

Check模块返回的Error，如果不做分类，上层只能采用“一刀切”策略：要么全部弹窗，要么全部静默。

常见的分类方式如下：

有了这些分类，上层组件就能给出更精准的兜底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头疼，建议先做三件事：梳理它到底在检查什么；给每个检查项明确级别和错误码；把外部依赖全部注入改写一遍。做完这三步，很多说不清楚的问题大概都会在整理的过程中露出水面。我自己的经验是，所谓核心类的模块维护，最重要的事情不是“写得有多巧妙”，而是“让每一个后来者都能在半小时之内搞懂规则，放心的动手改”。