抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

快速开始

收藏
我的收藏

准备环境

项目
接入要求
抖音客户端
39.8.0
基础库
4.25.0 及以上。使用更高版本新增能力时,还需满足相应能力的版本要求
开发者工具
4.5.7 及以上版本,下载地址
调试设备
准备满足支持条件的真机。模拟器仍存在能力限制,map 和 web-view 等场景需要真机验证。

AI 生成/迁移

lynx-miniapp-skills 是面向 Lynx 渲染抖音小程序的 Agent 能力包,包含 Lynx 小程序生成的流程要求及能力支持差异,配合 Agent 完成快速自动生成或迁移。详见文档《skills》介绍。

详细接入流程

1.页面启用 Lynx

先选择一个页面,在该页面对应的 JSON 配置文件中增加 renderType。例如,pages/index/index 页面对应 pages/index/index.json:
{ "renderType": "lynx" }
如需全局启用,也可以在 app.json 中配置 renderType。首次迁移建议仅配置试点页面,以便逐页核对差异。

2.设置 Lynx 生效的基础库版本

如果页面依赖高于基础支持版本的能力,可在 app.json 中设置 renderOptions.lynx.minSDKVersion。例如,业务依赖基础库 4.28.0 的能力时:
{ "renderOptions": { "lynx": { "minSDKVersion": "4.28.0" } } }
将上述字段合并到现有配置,不要覆盖 pages 等其他字段。未设置 minSDKVersion 时,接入资料说明默认从最低支持的基础库版本生效。
minSDKVersion 控制 Lynx 渲染的生效门槛,不等于控制台中的“小程序最低可用基础库版本”。低于 Lynx 生效门槛或不支持 Lynx 的环境会回退为 WebView;如果仍允许这些用户进入小程序,就必须保留可用的 WebView 路径。

3.确认实际渲染类型

重新编译并在真机打开页面。在页面实例中检查 renderType:
Page({ onLoad() { if (this.renderType === 'lynx') { console.log('当前页面使用 Lynx 渲染'); } else { console.log('当前页面按 WebView 兼容路径处理'); } } });
低版本基础库可能没有 renderType 字段,因此应优先判断是否等于 'lynx',不要只判断是否等于 'webview'。自定义组件实例也提供该字段。开发者工具模拟器中的 Lynx 标识可辅助确认,但不能代替真机运行结果。

4.适配滚动区域

Lynx 页面默认不提供 WebView 式的全局页面滚动。需要滚动的区域应使用 scroll-view,并设置明确的容器尺寸。以下是用于验证基础滚动的最小示例:
<scroll-view scroll-y="{{true}}" style="height: 400px;"> <view style="height: 800px;"> <text>Lynx 滚动区域</text> </view> </scroll-view>
确认内容能够在容器内滚动,再根据业务布局调整高度。原本依赖页面滚动回调和 tt.pageScrollTo 的逻辑,需要迁移到滚动容器的受支持能力。

5.适配小程序能力

完成本页后,应能在目标真机看到页面内容、确认 renderType 为 lynx,并在示例容器内正常滚动。若实际使用 WebView,先核对版本条件及页面配置。接下来按“能力支持与差异”检查业务依赖,并根据 Lynx 小程序支持情况适配。

Q & A

Lynx 是在客户端高版本才支持,是否低版本就完全运行不了小程序了?

不是,低版本有其他兼容方案。为了保证线上小程序能可靠运行,可任取以下其中一种策略:
    a.提高「基础库最低可用版本」,设置为 Lynx 所支持的版本,该策略意味着放弃低版本用户。版本分布占比见:版本分布
    b.兼容好 WebView,我们会在不支持 Lynx 的版本自动降级为 WebView 渲染。在选择兼容 WebView 的策略后,开发者在上线前需要保障两种渲染模式都能正确渲染。