企业官网建设流程全解析

做鸿蒙 H5 混合开发的人，大概率都翻过 Web 组件里那两个执行 JavaScript 的接口：runJavaScript()和runJavaScriptExt()。光看名字一个是“执行”，一个是“扩展执行”，好像差不多，但真正上手写业务的时候，你会发现它们在参数设计、返回值处理、甚至能不能拿到复杂数据上，差距比想象中大得多。这篇文章我就用实际开发中的对比视角，把这两个 API 的底层差异、典型用法和踩坑记录都摊开讲清楚，给正在做鸿蒙 Web 混合开发的同学一个可直接参考的对照。

1. 项目背景：为什么混合开发绕不开这两个 API

1.1 鸿蒙 H5 混合开发的典型交互场景

做鸿蒙应用时，很多团队会优先选择 H5 混合开发，原因很现实：一套前端代码能同时覆盖多端，业务迭代速度快，尤其是活动页、营销页、动态下发的页面，用 H5 承载比原生开发灵活太多。但混合开发的关键问题在于，H5 页面运行在 Web 组件里，它和鸿蒙原生侧的通信不能像普通页面那样直接调函数，必须依赖系统提供的桥接能力。

最常见的两类交互：第一类是原生向 H5 主动发消息，比如用户点击了原生按钮，需要通知网页跳转某个路由；第二类是原生需要从 H5 侧取数据，比如网页里通过前端逻辑算好了某个订单金额，原生要拿这个值去调支付接口。这两类场景落到代码层，就是你要在鸿蒙侧执行一段 JavaScript 脚本，然后把执行结果拿回来。

这时候你打开开发者文档，会发现执行脚本的入口不止一个。runJavaScript()是最早的那版接口，能跑脚本、能拿字符串返回值；runJavaScriptExt()是增强版，官方说支持更复杂的参数和对象返回。但对一个刚上手的人来说，文档里就一两句话，根本看不出来“复杂参数”到底是什么、什么时候非用 Ext 不可。我最初也因为图省事统一用runJavaScript()，直到被一个返回 JSON 字符串的接口折腾了半天才意识到问题出在哪。

1.2 混合开发里“执行脚本”的几个基础前提

不管用哪个接口，先要明确一个前提：这些 API 都挂在 Web 组件对应的控制器上，也就是你通过webviewController创建出来的那个对象。你必须在 Web 组件加载完成之后才能调用，否则网页的 JavaScript 上下文还没准备好，脚本执行会直接失败。

我习惯在onPageEnd回调里做初始化标记，因为onPageEnd表示页面加载完毕，此时执行注入脚本最稳妥。另外，这两个接口虽然都能在页面上执行任意 JavaScript 代码，但它们执行的脚本跑在网页的全局作用域里，所以你有权限访问网页里定义的全局函数和变量。反过来说，如果网页里的某些变量是用const或let在局部作用域声明的，外部脚本不一定能直接访问到，这不算接口问题，是 JavaScript 本身的作用域机制，很多时候排查半天其实是这里踩了坑。

2. runJavaScript() 的基础用法和数据返回限制

2.1 最简单的脚本执行写法

先看runJavaScript()的标准用法。它接收一个字符串参数，这个字符串就是要执行的 JavaScript 代码，执行结果通过回调返回。代码大概长这样：

import { webview } from '@kit.ArkWeb'; let controller: webview.WebviewController = new webview.WebviewController(); // 在合适时机（如 onPageEnd 之后）调用 controller.runJavaScript('document.title', (error, result) => { if (!error) { console.info(`页面标题为：${result}`); } });

这里有几个细节值得注意。第一，result的类型永远是string，哪怕你执行的是1 + 1这种数字表达式，拿回来的也是字符串"2"，需要的话得自己Number(result)转一下。第二，回调的第一个参数是error，如果网页没加载完、或者脚本语法错误，都会通过这个参数反馈，不能只处理成功分支。第三，脚本内容如果不涉及页面状态，想在任意时机执行也可以，但建议还是放在页面加载完成后，避免偶发性的“脚本未执行”问题。

2.2 想拿 JSON 对象？这里就是第一个大坑

runJavaScript()设计之初面向的是“简单返回值”，所以它只能返回字符串。但真实业务里，H5 侧给原生传的往往不是单个字符串值，而是一个对象。比如 H5 页面有一份商品信息：

window.getGoodsInfo = function () { return { id: '1001', name: '测试商品', price: 199.9, tags: ['新品', '推荐'] }; };

你如果用runJavaScript()去调：

controller.runJavaScript('getGoodsInfo()', (error, result) => { // result 实际上会是一个 JSON 字符串，应用层再自己 JSON.parse });

看起来好像也能用，因为result里拿到的其实是JSON.stringify之后的结果。但问题在于：如果页面里返回的对象含有循环引用、undefined字段、或者function类型的值，序列化过程会发生意外。undefined会被丢掉，function会变成undefined或直接报错，循环引用更是直接让整个转换失败，你在原生侧只能收到一个错误回调，根本拿不到想要的 JSON。这就是runJavaScript()一个明显的短板：它内部对返回数据的处理是偏“口语化”的，适合简单值，不适合把复杂对象当数据通道来用。

刚接触混合开发的同学遇到这类问题，第一反应是检查 JavaScript 代码本身，但代码在浏览器里明明正常，一放到 Web 组件里就出问题，其实就是接口的数据返回策略撑不住复杂对象。我自己就被一个卖场页面的配置对象坑过一次，那个对象里嵌套了两层数组和几个可选字段，用runJavaScript()拿回来的字符串怎么JSON.parse都少字段，后来换成runJavaScriptExt()才稳定。

3. runJavaScriptExt() 增强能力拆解

3.1 参数不再是裸字符串

runJavaScriptExt()和runJavaScript()最直接的区别在入参：前者不再接收一个裸的字符串，而是接收一个JavaScriptOptions对象。这个对象里最核心的字段是script，也就是你要执行的 JavaScript 代码。但它的设计意图不只是“换一层皮”，而是让调用方可以传递更多控制信息，为后续能力扩展留出空间。

我实际项目中用的方式是先把要执行的脚本拼好，再构建选项对象：

import { webview } from '@kit.ArkWeb'; const options: webview.JavaScriptOptions = { script: 'window.getGoodsInfo ? getGoodsInfo() : null' }; controller.runJavaScriptExt(options, (error, result) => { if (!error) { console.info(`获取结果：${JSON.stringify(result)}`); } });

看到这里你可能觉得区别不大，无非是把字符串挪到了对象的script字段里。真正拉开差距的是返回值处理。runJavaScriptExt()在设计上对“对象返回”的处理更友好，它会把结果处理成可以直接映射为 ArkTS 数据结构的格式。实际调试中，我在回调里拿到的result不再是一坨需要自己猜结构的字符串，而是能相对可靠地转换成一个对象。这对后续传参给业务模块、甚至直接塞进状态管理里，都省了很多脏活。

3.2 返回值处理逻辑更贴合 ArkTS 侧使用习惯

在鸿蒙开发里，ArkTS 是主要面向 UI 和业务逻辑的开发语言，它对类型的约束比普通 JavaScript 严谨得多。runJavaScript()返回的字符串虽然也能JSON.parse，但解析出来的对象的类型推断、空值处理，都需要开发者自己小心处理。runJavaScriptExt()的价值在于，它更方便地把 H5 侧的 JavaScript 对象和原生侧的 ArkTS 对象做映射，在设计之初就考虑了这类混用场景。

举个例子，我需要从 H5 拿一个用户行为追踪的数据包，里面有几个必填字段和几个可选字段：

interface TrackData { pageName: string; duration: number; extra?: Record<string, string>; }

用runJavaScriptExt()时，我可以直接在 ArkTS 侧声明接收类型，然后对回调结果做转换。虽然它底层还是逃不开序列化，但至少接口层面省掉了“先拿字符串再自己 parse”这一步，而且错误信息里能看出更多线索。对于需要频繁传递结构化数据的混合开发项目，这个改进带来的维护收益是很明显的。

3.3 官方文档没细说的异步执行差异

还有一点是网上讨论比较少但我实测有效果的差异：runJavaScriptExt()在面对异步 JavaScript 函数时，体验比runJavaScript()要稳。H5 侧有些数据不是同步返回的，需要等一个Promiseresolve。比如：

window.getAsyncData = function () { return Promise.resolve({ code: 0, data: [1, 2, 3] }); };

你直接同步调getAsyncData()拿到的实际是一个 Promise 对象，不是数据。有同事试过把整个 Promise 执行逻辑全部塞进runJavaScript()的脚本里，手动.then()然后通过全局变量存结果，再用第二段脚本去读，虽然能跑通，但逻辑绕、需要轮询等待，体验很差。而runJavaScriptExt()所在的新版接口体系里，异步场景的处理要平滑一些，脚本内返回的 Promise 在部分 SDK 版本里能被正确解析成最终值，这个能力对做复杂 H5 对接的人来说简直是救命的。

不过我必须强调一点：不同 API 版本对异步行为的支持不完全一致，官方文档也没有把每种场景都写死。我建议你接入后，在真机或模拟器上专门跑一个“返回 Promise 的数据页”做验证，确认你手头这个 SDK 版本的行为符合预期，再放心用到生产环境。

4. 两个 API 的核心区别与选型建议

4.1 参数、返回值、调用方式对照

我把实际开发中最关心的几个维度整理成了对照表，方便你快速判断手里的需求该用哪一个：

这个表不是要用 Ext 全面替代旧接口，而是告诉你边界在哪里。像我就保留了runJavaScript()在调试场景里用，因为打开 DevTools 协议配合它做临时脚本注入很方便，少写一个对象包装，效率高。但凡是正式业务代码里要传结构化数据，我清一色用runJavaScriptExt()，省心。

4.2 不同场景下的接口选择标准

判断标准其实就三条。第一，数据复杂度：返回的是字符串、数字、布尔值，用哪个都行，我默认用runJavaScript()；返回的是对象、数组、嵌套结构，直接选runJavaScriptExt()，别给自己埋坑。第二，调用频率：如果原生和 H5 之间的通信频率高，比如页面滚动时要不断上报数据，建议用runJavaScriptExt()，它面向对象返回的特性在频繁传输中更稳定。第三，维护成本：项目里有多个开发同时维护桥接层，尽量统一用 Ext，因为选项对象的语义比裸字符串清楚，别人看代码时不容易误会。

另外提一个容易被忽略的点：脚本拼接方式也会影响稳定性。不要直接在代码里拼长字符串 SQL 一样把业务逻辑全塞进去，那样代码难读、也容易出错。最好在 H5 侧把功能封装成全局函数，原生侧只负责调用这个函数并取回结果，责任边界清楚，排查问题时也能快速定位是 H5 还是原生的问题。

5. 实测记录、常见问题与排错技巧

5.1 一组实测对比数据

我自己用同一个测试页面分别调两个接口跑了 20 次，页面里准备了三类返回值：纯字符串、普通对象、带有嵌套数组的复杂对象。结果如下：

注意，这个结果不能代表所有版本，但它能说明趋势：数据越复杂，runJavaScript()的字符串序列化链路越容易出问题，而 Ext 的稳定性明显更好。所以如果你手头的项目已经被偶发的“数据少了几个字段”困扰，而你还在用runJavaScript()，强烈建议先换个接口验证一下，很多玄学问题其实就这么解决了。

5.2 高频报错与排查思路实录

问题一：调用时机不对，报“Cannot execute javascript”之类错误

这个我遇到太多次了。Web 组件还在加载时就去执行脚本，接口会直接失败。解决方法是把脚本执行逻辑放到onPageEnd事件之后再触发，或者用一个标记量记录页面是否已加载完成。如果你有多个地方都可能触发脚本，最好做一个统一的“页面就绪再执行”的消息队列，避免竞态。

问题二：复杂对象返回不一致，偶尔少字段

就像我前面说的，优先把runJavaScript()换成runJavaScriptExt()。同时检查 H5 侧返回的数据里有没有undefined值、循环引用、Date对象这种特殊类型。Date对象在序列化时会变成字符串，如果你原生侧期望的是时间戳，这里就会产生隐蔽的 bug。

问题三：中文字符乱码或编码不一致

慌的人会去改 Web 组件的字符集设置，其实多半是脚本拼接时编码出了问题。建议脚本内容里不要直接拼中文，改成通过全局函数传参，或者把中文先encodeURIComponent()再传递，在原生侧拿到后解码。这个方法在处理用户输入、搜索词传递时尤其好使。

问题四：接口回调一直不触发

先检查控制器对象是否被提前释放了。Web 组件销毁后，控制器实例不能再执行脚本，回调自然也不会回来。另一个常见原因是页面发生跳转，执行上下文被替换，之前发出去的脚本执行请求还在排队，但页面已经不是原来的页面了。这种情况建议把业务逻辑拆成“页面加载完-执行脚本-上报结果”三步，每一步都做状态校验。

5.3 混合开发调试时能省时间的几个小工具

调试 JavaScript 注入问题，我不建议只在鸿蒙工程里打日志。你可以打开 Web 组件的调试模式，用桌面浏览器远程调试 H5 页面，这样 JavaScript 侧的错误能直接看见。具体做法是在初始化 Web 组件时开启调试，然后用 DevTools 协议连接。这样你就能看到是脚本本身报错了，还是数据序列化出问题，定位效率高很多。

另一个技巧是写一个“万能脚本”工具函数：接收函数名和参数，拼接成调用脚本，再统一走runJavaScriptExt()执行。类似这样：

function callH5Function(controller: webview.WebviewController, funcName: string, ...args: string[]): Promise<string | undefined> { const script = `window.${funcName} ? ${funcName}(${args.join(',')}) : null`; const options: webview.JavaScriptOptions = { script }; return new Promise((resolve, reject) => { controller.runJavaScriptExt(options, (error, result) => { if (error) { reject(error); } else { resolve(result); } }); }); }

有了这个函数，业务侧代码会清爽很多，调 H5 函数就跟调原生函数差不多。工具函数本身不复杂，但对整个项目的可维护性提升很明显，值得花几分钟写一个。

5.4 哪些坑是接口之外需要提前预防的

最后分享几个和接口本身无关、但开发中高频出现的坑。首先是 Web 组件的缓存问题：H5 页面更新了，但 Web 组件还在用缓存，导致你的注入脚本调用的函数还是老版本，行为完全对不上。排查这类问题时，手动刷新页面、清缓存是第一步。其次是前端代码里开启了严格模式，某些全局函数没有挂到window上，你原生侧怎么调都是undefined。解决方法是让前端同事显式把方法挂到window，或者你执行脚本时带上兼容判断，先检测函数是否存在。

还有一个很容易忽略的点：如果你在 H5 页面里用了content-security-policy之类的安全策略，外部注入的某些脚本执行可能受限。这种情况不是接口问题，是前端安全策略拦截了动态执行的代码。处理方式要么和前端协调放宽部分策略，要么把要执行的功能封装成页面内本来就允许的脚本路径。

混合开发本身就是一个不断摸边界的过程，Web 组件提供的接口只是通道，真正决定业务跑得顺不顺的，往往是对这些接口边界的理解和长期踩坑后的预判。runJavaScript()和runJavaScriptExt()的选择只是其中一个细节，但把这个细节处理好了，后面复杂数据交互的稳定性会省下你大量排查成本。