源码侦察实战：以 escape-string-regexp 为例找出平台耦合点-迪斯科星球

源码侦察实战：以 escape-string-regexp 为例找出平台耦合点

专栏：HarmonyOS 三方库适配实战（7/30）
前置条件：已完成第 6 篇候选卡，并锁定准确源码快照。

摘要

拿到一个 JavaScript 或 TypeScript 库后直接搜索替换，往往会把入口、测试和平台能力混在一起。更稳妥的方法是先锁定版本，再做四遍侦察：从包清单确认入口，从 import/export 画依赖图，从关键字定位运行时耦合，再用测试确定真正的核心路径。本文用escape-string-regexp@5.0.0演示可复核过程。交付物是“哪里值得改、先改什么、凭什么这样判断”，不是一句笼统的“代码没问题”。

侦察输入与输出

输入必须是第 6 篇锁定的源码快照，不能扫描工作区里随时变化的main分支。输出至少包含：

入口与公开符号；
模块依赖图；
平台耦合命中及上下文；
正常、边界、错误测试对应的调用路径；
每个问题的证据、影响、处理策略和验证动作。

如果源码快照、包清单或许可证缺失，先返回候选阶段，不要开始修改。

图 1：四遍源码侦察（示意图）。输出必须包含位置、核心路径判断、风险、处理策略和验证动作。

第一遍：从包清单和入口向里走

先看包清单，不要先全局搜索。记录name、version、main、依赖字段和脚本，再打开真实入口文件。HarmonyOS 模块级oh-package.json5的main字段用于描述入口文件；后续打包时入口与实际导出必须一致。

package manifest └── main / exports ├── public function A ├── public class B └── re-exported type C

把入口暴露的符号分为三类：本篇必须保留、可能保留、内部实现。第一次适配只承诺最小公共面，避免为了“完整”把调试工具和内部帮助函数一起导出。

第二遍：画最小依赖图

用搜索找出静态导入、动态导入和 CommonJS 入口：

rg-n--glob'*.ts'--glob'*.js'`-e'^\s*import\s'-e'^\s*export\s'`-e'\bimport\s*\('-e'\brequire\s*\('src test

不要只统计命中数量，要把核心调用链画出来。例如：

public entry ├── normalize.ts │ └── whitespace.ts └── validate.ts └── error.ts

再给节点加标签：core表示纯逻辑，adapter表示平台接口，test-only表示只在测试中使用，generated表示生成文件。这样遇到fs命中时，才能区分它是在发布脚本里，还是在运行期核心路径里。

第三遍：按风险族扫描平台耦合

动态语言行为

rg-n--glob'*.{ts,js}'`-e'eval\s*\('-e'new\s+Function'`-e'Object\.(defineProperty|create|assign)'`-e'\[[^\]]+\]\s*='.

华为官方从 TypeScript 到 ArkTS 的适配规则说明了静态类型、运行时改变对象布局、结构类型、require和部分标准库能力的限制。命中动态属性写入时，应追踪对象从哪里创建、属性集合是否固定、读写点是否能收敛为明确模型。

Node.js 与浏览器运行时

rg-n--glob'*.{ts,js}'`-e'\bprocess\b|\bBuffer\b|\bglobalThis\b'`-e'\bwindow\b|\bdocument\b|\blocalStorage\b'`-e'from\s+["''](?:fs|path|http|https|crypto)["'']'.

命中后分四种处理：删除非核心能力、抽象成窄接口、替换为 HarmonyOS 能力、或停止采用。不要先写一个巨大的“兼容层”掩盖所有差异。

时间、并发与副作用

rg-n--glob'*.{ts,js}'`-e'setTimeout|setInterval|queueMicrotask'`-e'^\s*(console\.|[A-Za-z_$][\w$]*\s*=)'src

模块顶层执行也属于风险。华为官方模块加载副作用及优化指出，模块被导入时顶层代码会立即执行；循环依赖还可能让导入值尚未初始化。入口文件应尽量只声明和导出，不在加载时做网络、文件、注册或状态修改。

第四遍：让测试告诉你什么不能改坏

搜索测试里的公开 API 调用和期望值：

rg-n--glob'*test*'--glob'*spec*'`-e'expect\s*\('-e'assert'-e'toEqual|toThrow'.

把测试映射到公开符号，而不是只统计“有多少测试”。若一个导出函数没有任何可观察行为基线，先补向量，再改实现。

把命中写成可复核的问题清单

| ID | 位置 | 命中 | 是否在核心路径 | 风险 | 处理 | 验证 | | --- | --- | --- | --- | --- | --- | --- | | R-01 | src/options.ts:18 | 动态属性写入 | 是 | high | 改明确模型 | 正常/未知键用例 | | R-02 | scripts/release.ts:9 | process.env | 否 | low | 不进入 HAR | 包内容检查 | | R-03 | src/index.ts:1 | require | 是 | high | 标准 import | SDK 编译 |

风险分级建议：

high：入口、核心调用路径、运行时必经；
medium：可选能力或错误分支；
low：测试、发布脚本、文档示例，不进入目标包。

图 2：风险矩阵（示意图）。同一关键字出现在核心路径和发布脚本中，处理优先级并不相同。

可复查案例：escape-string-regexp@5.0.0

教学夹具不能替代三方库证据。本篇改用escape-string-regexp@5.0.0作为侦察样本：它是公开 npm 包，固定版本页显示运行时依赖为 0，包页与源码仓库均可公开访问。该样本的目的，是验证侦察流程不会把“纯字符串逻辑、无运行时依赖”的包误判为平台耦合包；它不代表该包已直接接入任意 HarmonyOS 工程。

锁定输入

npm 包：escape-string-regexp@5.0.0；
源码仓库：sindresorhus/escape-string-regexp；
扫描对象：固定发布包入口index.js与测试文件；
运行时依赖：0，以该版本 npm 依赖页为准。

在解压后的固定包目录执行：

rg-n--glob'*.{ts,js}'`-e'\beval\s*\('-e'new\s+Function'`-e'\brequire\s*\('-e'\bprocess\b|\bBuffer\b'`-e'\bwindow\b|\bdocument\b|\blocalStorage\b'`-e'from\s+["''](?:fs|path|http|https|crypto)["'']'.

本次固定版本样本的上述模式扫描结果为no_matches。这条结果只支持一个窄结论：指定模式没有出现在该发布快照的 JavaScript 源码中；它不等于“该包已在 HarmonyOS 可运行”，也不覆盖正则语义、导入格式、ArkTS 类型约束或打包配置。

从“无命中”进入下一层验证

这个案例没有发现 Node.js、DOM 或动态执行命中，因此下一关不是虚构兼容层，而是将入口调用放进最小 ArkTS 适配工程，用目标 SDK 编译验证导入、导出和正则行为。可观察的宿主逻辑基线为：

input: How much $ for a 🦄? output: How much \$ for a 🦄\? input: a-b output: a\x2db

若目标 SDK 在import、正则字面量或类型处报错，应记录首个错误的文件、行号、问题族和最小修复；若编译通过，也只能证明本次工程与目标 SDK 的编译层可用，模拟器和真机仍需单独验证。

常见失败：全库搜索替换

看到any就替换成Object、看到require就替换成import * as，可能改变类型语义或导出形态。正确顺序是：确定调用路径，识别问题族，选择一个代表性错误，设计适配模式，再批量处理同类问题。

本篇产物与下一篇门槛

本篇产物是一张模块依赖图和一份带验证动作的风险清单。进入第 8 篇前，应能指出第一个目标 SDK 编译错误属于哪个文件、哪个问题族，以及修复后用什么证据确认。

官方来源

从 TypeScript 到 ArkTS 的适配规则：用于定位静态类型、对象布局、结构类型、require和标准库限制。访问日期：2026-10-18。
模块加载副作用及优化：用于核对顶层代码执行、循环依赖和加载顺序风险。访问日期：2026-10-18。
oh-package.json5：用于核对模块入口和依赖字段。访问日期：2026-10-18。
escape-string-regexp 5.0.0：用于核对固定包版本、用途和依赖信息。访问日期：2026-10-21。
escape-string-regexp 源码仓库：用于定位发布包的上游源码与维护者说明。访问日期：2026-10-21。

验证声明

本文于 2026-10-21 核对华为官方适配文档、模块副作用文档、oh-package.json5 文档，以及escape-string-regexp@5.0.0的 npm 包页和公开源码仓库；并对固定发布快照执行了文中列出的文本模式扫描，结果为no_matches。该结果是静态侦察证据，不是 ArkTS 编译、模拟器运行或真机验证。本文不声称该 npm 包已经在任意 HarmonyOS 工程中完成接入；第 8 篇将以目标 SDK 编译补齐下一层证据。

企业官网建设流程全解析