源码侦察实战以 escape-string-regexp 为例找出平台耦合点专栏HarmonyOS 三方库适配实战7/30前置条件已完成第 6 篇候选卡并锁定准确源码快照。摘要拿到一个 JavaScript 或 TypeScript 库后直接搜索替换往往会把入口、测试和平台能力混在一起。更稳妥的方法是先锁定版本再做四遍侦察从包清单确认入口从 import/export 画依赖图从关键字定位运行时耦合再用测试确定真正的核心路径。本文用escape-string-regexp5.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}-eeval\s*\(-enew\sFunction-eObject\.(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-efrom\s[](?:fs|path|http|https|crypto)[].命中后分四种处理删除非核心能力、抽象成窄接口、替换为 HarmonyOS 能力、或停止采用。不要先写一个巨大的“兼容层”掩盖所有差异。时间、并发与副作用rg-n--glob*.{ts,js}-esetTimeout|setInterval|queueMicrotask-e^\s*(console\.|[A-Za-z_$][\w$]*\s*)src模块顶层执行也属于风险。华为官方模块加载副作用及优化指出模块被导入时顶层代码会立即执行循环依赖还可能让导入值尚未初始化。入口文件应尽量只声明和导出不在加载时做网络、文件、注册或状态修改。第四遍让测试告诉你什么不能改坏搜索测试里的公开 API 调用和期望值rg-n--glob*test*--glob*spec*-eexpect\s*\(-eassert-etoEqual|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-regexp5.0.0教学夹具不能替代三方库证据。本篇改用escape-string-regexp5.0.0作为侦察样本它是公开 npm 包固定版本页显示运行时依赖为 0包页与源码仓库均可公开访问。该样本的目的是验证侦察流程不会把“纯字符串逻辑、无运行时依赖”的包误判为平台耦合包它不代表该包已直接接入任意 HarmonyOS 工程。锁定输入npm 包escape-string-regexp5.0.0源码仓库sindresorhus/escape-string-regexp扫描对象固定发布包入口index.js与测试文件运行时依赖0以该版本 npm 依赖页为准。在解压后的固定包目录执行rg-n--glob*.{ts,js}-e\beval\s*\(-enew\sFunction-e\brequire\s*\(-e\bprocess\b|\bBuffer\b-e\bwindow\b|\bdocument\b|\blocalStorage\b-efrom\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-regexp5.0.0的 npm 包页和公开源码仓库并对固定发布快照执行了文中列出的文本模式扫描结果为no_matches。该结果是静态侦察证据不是 ArkTS 编译、模拟器运行或真机验证。本文不声称该 npm 包已经在任意 HarmonyOS 工程中完成接入第 8 篇将以目标 SDK 编译补齐下一层证据。