mpx2rn

Mpx 跨端输出 RN 开发与适配指南

背景介绍

Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展支持的跨端开发框架，支持将同一套代码输出到小程序（微信、支付宝、百度等）、Web 和 React Native 平台。Mpx2RN 在编译时和运行时对模板、脚本、样式与 JSON 配置四大维度的开发能力进行了全面抹平，但与小程序、Web 平台仍存在一定能力差异。

适用场景

本 SKILL 是 Mpx2RN 开发适配的统一指南，覆盖模板、脚本、样式、JSON 配置四大维度。涉及 Mpx2RN 的任务均应在动笔前阅读本 SKILL 的通用约束与适配原则，包括但不限于：

• 技术方案设计：评估需求在 RN 平台的可行性、跨端兼容方案选型、是否需要文件级条件编译或混合开发等;
• 旧项目跨端适配改造：对已基于小程序规范编写、未适配 RN 的存量组件进行兼容性补齐（参见下文任务一）;
• 页面 / 组件开发迭代：从零编写或迭代符合 RN 跨端兼容规范的 .mpx 页面与组件（参见下文任务二）;
• 编译和运行时报错排查：定位 RN 平台特有的编译错误（如样式空选择器、保留关键字、缩进敏感预处理器报错等）与运行时差异;
• Code Review：以本 SKILL 的通用约束与适配原则为标准对照检查跨端兼容性。

不适用场景

以下场景与 Mpx2RN 无关，不应调用本 SKILL：

• 仅面向小程序平台（微信、支付宝、百度等）的 Mpx 开发问题;
• React Native 原生开发问题（不经 Mpx 编译的纯 RN 项目）;
• Mpx 跨端输出 Web（Mpx2Web）相关问题。

知识库索引

知识库使用建议

参考文档体量较大，不要一次性预读全部参考，按需取用即可：

1. 入口只读本 SKILL.md：完整读完本文档（含下方通用约束与任务流程）足以覆盖 80% 常见场景的判断；不要在动笔前预读 references 目录。
2. 触发式读取：只在任务流程或通用约束中明确指向某份参考时读取，且仅读取与当前问题相关的小节（参考文档均含目录与章节锚点，使用 grep / 锚点跳读，不要整文件 Read）。
3. 典型任务的最小阅读集（仅当本 SKILL.md 已无法判断时再补充）：
   • 已有组件 RN 跨端适配改造：识别问题维度后再读对应能力参考的相关小节，通常 1–2 份足够（如样式改造主要查 rn-style-practice.md）。
   • 新建 RN 跨端兼容组件：先按本 SKILL.md 的通用约束起手，遇到能力存疑（某属性是否支持、某 API 是否存在）时再点查对应参考。
   • 排查特定编译报错：直接定位到报错维度的能力参考相关小节。
   • 使用或排查原子类：读取 rn-atomic-css.md；仅需核对底层样式属性时再补读 rn-style-reference.md，不要预读全部样式参考。
4. 何时读取 single-file-component.md：仅当不熟悉 Mpx SFC 基本结构时读取；已熟悉 SFC 写法可跳过。

通用约束与适配原则

无论是适配改造、新建组件还是 Code Review，跨端兼容均需严格遵循以下通用约束：

跨平台兼容约束

产物代码须在原平台与 RN 平台均能正常运行。引入「RN 支持但原平台不支持」的写法（如 numberOfLines@ios|android|harmony / hairlineWidth 等 RN 等效实现）时，不要替换原平台已有写法，而应：

• 用条件编译将该 RN 写法限定在 RN 平台输出（模板属性后缀 @ios|android|harmony、样式与脚本 @mpx-if 包裹等）；
• 同步用条件编译保留原平台原有写法，避免改造引入原平台行为退化。

该原则贯穿模板 / 脚本 / 样式 / JSON 四个维度，下方各约束与样式约束 #3 的「双轨」条目即此原则的具体落地。

模板（template）约束

1. 基础组件优先：使用 模板能力参考 · 基础组件 中标注 RN 支持的基础组件与其支持属性/事件，不要使用 RN 不支持的属性或事件；如用户通过 rnConfig.customBuiltInComponents 编译配置扩充拓展了基础组件能力，以用户说明为准。
2. 页面滚动：RN 平台页面默认不可滚动，onPullDownRefresh / onReachBottom / onPageScroll 不会触发；需要滚动时使用 scroll-view 包裹并使用其等效能力。
3. 事件冒泡/捕获：仅基础通用事件（tap / longpress / touchstart / touchmove / touchend / touchcancel）支持冒泡和捕获；其余事件不支持。
4. 模板内方法调用：模板 Mustache 表达式不支持普通方法调用，需通过 computed / wxs 实现（i18n 翻译函数除外）。
5. i18n：组合式 API 中 useI18n() 解构出的翻译函数必须以原名 t / tc / te / tm 暴露至模板的 return，禁止重命名。
6. 事件传参：传递自定义参数给事件处理器时，优先使用事件内联传参语法（如 bindtap="handleTap('param')"），而不是通过 data- dataset 属性传参。
7. 文字优先使用 text 包裹：虽然框架支持在 view 中直接插入文字（编译时自动补 text），但会引入额外的 view 层级，存在性能开销。应优先使用 text 组件显式包裹文字内容；text 的跨平台布局对齐方案见 样式开发最佳实践 · text 跨平台布局对齐。

脚本（script）约束

1. 生命周期 / 构造选项：仅使用 逻辑能力参考 中标注 RN 支持的生命周期与构造选项；避免使用 onShareTimeline / onTabItemTap / onAddToFavorites / onSaveExitState 等 RN 不支持项。
2. 环境 API：通过 @mpxjs/api-proxy 提供的统一 mpx.xxx API 调用环境能力，避免直接使用 wx.xxx / my.xxx；具体支持范围见 环境 API 参考；如用户通过 custom 配置扩充拓展了环境 API 能力，以用户说明为准。
3. selector 映射：脚本中的 selectComponent / selectAllComponents / createSelectorQuery / createIntersectionObserver 等 selector API 仅支持 #id / .class，且对应模板节点须声明空 wx:ref 以建立编译期 selector 映射。详见 逻辑能力参考 · 实例方法与属性。
4. 保留关键字：id / dataset / data 是页面/组件实例的保留关键字，任何挂载到实例上的数据 key（包括 props / data / computed / methods / setup return / inject 等）都不得使用这三个名称作为 key，否则会触发 reserved keyword of miniprogram 编译期/运行期报错。命名时使用语义化别名（如 itemId / rowData / pageData）替代。

样式（style）约束

1. 样式能力判断口径：样式属性支持情况以 样式能力参考 为准，不要基于 RN 原生样式支持能力判断。Mpx2RN 已抹平支持的简写属性展开、CSS 变量、calc()、媒体查询、rpx 单位、颜色格式、文本继承等能力可直接使用，无需条件编译或替换写法。

2. 选择器单类化：禁止使用复合/伪类/伪元素等 RN 不支持的选择器，必须改造为单类等效实现，并同步修改 <template> 与 <script>（如 createSelectorQuery）中对应的引用。常见兼容方案见 样式开发最佳实践 · 选择器使用建议。

   • Bad Example: .list .item { color: red; }
   • Good Example: .list-item { color: red; }
   • 注意：用逗号分隔的并列形式（如 .classA, .classB { ... }）等价于多条单类选择器规则共享同一样式块，仍属于单类选择器范畴，无需拆分或合并为新单类，可直接使用。
   • UnoCSS 例外：原子类的 hover: variant 由编译器转换为组件 hover style，不等同于在 <style> 中编写 .button:hover；普通 CSS 伪类仍不支持。

3. 优先使用模板指令进行动态样式绑定：使用 wx:class / wx:style 指令，避免在 class / style 属性内拼接 {{}} 插值表达式。

   • Bad Example: <view class="item {{isActive ? 'active' : ''}}">
   • Good Example: <view class="item" wx:class="{{ {active: isActive} }}">

4. 优先使用跨端兼容方案：常见样式属性的跨端兼容方案见 样式开发最佳实践。下表区分两类处理方式：

   • 等效替换（替换后写法在原平台与 RN 平台均生效，可直接全平台使用）
     • 复合选择器 → 等效单类选择器
     • 子元素伪类（:first-child 等）→ wx:class + index 判断
     • 伪元素（::before / ::after）→ 真实节点替代
     • 点击态伪类（:active）→ hover-class / hover-stay-time
     • rem / em → rpx
     • 数值型 font-weight → normal / bold
     • 隐藏元素：避免 display: none，使用尺寸归零 + overflow: hidden
     • grid / float → Flex 布局
   • 双轨保留（原平台原写法用条件编译保留，RN 侧新增等效实现，禁止只保留 RN 一侧）
     • 文本溢出：原平台保留 white-space / text-overflow / overflow: hidden 样式（用样式条件编译包裹整条规则），RN 侧通过模板属性 numberOfLines@ios|android|harmony 等效实现
     • 1rpx 极细线：原平台保留 1rpx 边框写法（用样式条件编译），RN 侧用 hairlineWidth 等效

5. 保留单位注释：保留原始样式中的 /*use rpx*/ 与 /*use px*/ 注释，编译期会据此批量切换样式单位。

6. 原子 CSS：项目启用 UnoCSS 或模板使用原子类时，读取 Mpx2RN 原子 CSS 能力参考。只使用 RN preset 与 Mpx2RN 样式编译器共同支持的工具类和 variants；不支持项会作为编译错误且不会进入产物。颜色透明度统一使用 bg-red-500/50 等斜杠 alpha 语法，不要使用 bg-red-500 bg-opacity-50 等独立 opacity 组合。

JSON 配置约束

1. 支持范围：应用、页面、组件三级 JSON 配置在 RN 平台的字段支持详情见 JSON 配置参考；不支持字段（如 tabBar）须通过条件编译隔离。
2. 动态生成配置：当需要分平台或分环境定义 JSON 配置时，使用 <script name="json"> 形式访问 __mpx_mode__ / __mpx_env__ 变量动态生成。

条件编译约束

当某项能力无法在 RN 平台等效实现时，使用条件编译进行分平台处理：

• 原平台条件：__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web'
• RN 平台条件：__mpx_mode__ === 'ios' || __mpx_mode__ === 'android' || __mpx_mode__ === 'harmony'

需遵循以下约束：

1. 最小化使用：条件编译是处理跨端不兼容的最后手段，不是首选方案。使用条件编译之前，应先确认是否存在无需条件编译的跨端兼容写法（参见样式开发最佳实践与各能力参考）。需要用条件编译时，仅最小包裹真正不兼容的片段，不要整段代码都用条件编译分叉。
2. 避免空选择器：样式条件编译产物中不得留下空选择器（无样式内容的选择器），整条规则（含选择器与花括号内容）须一并被条件编译包裹。详见 条件编译 · 避免产物中出现空选择器。
3. 缩进敏感预处理器（stylus / sass 等）中条件编译注释须与所在块体同级缩进：mpx 会将指令注释和未命中分支替换为等长占位注释，占位注释保留原缩进。指令注释若顶格写在缩进块内部，会截断块上下文，触发 expected "indent", got "outdent" 等解析错误。
   • Bad Example (顶格): .back-wrapper 块内 /* @mpx-if ... */ 顶格无缩进
   • Good Example (与块内属性同级): /* @mpx-if ... */ 与 position 等属性同列缩进
4. 各区块使用对应的条件编译语法：样式条件编译使用 /* @mpx-if (__mpx_mode__ === ... ) */ 注释语法；模板条件编译使用 wx:if="{{__mpx_mode__ === ...}}" 指令或 @mode / @_mode 属性后缀；脚本和 JSON 配置条件编译使用 if (__mpx_mode__ === ...) 条件语句，避免误用，详情参考 条件编译。

任务一：对小程序 Mpx 组件进行 RN 跨端适配改造

输入

基于小程序技术规范编写的 {name}.mpx 组件（已在小程序、Web 平台运行，但未适配 RN）。

输出

以用户指示为准；若无特殊指示则默认在原文件 {name}.mpx 中进行修改。输出修改后代码时应输出完整组件代码，避免使用省略号，确保用户可以直接复制或应用修改。

任务流程

1. 模板（template）适配改造

• 读取 模板能力参考，对 <template> 中使用的基础组件及其属性与事件逐一核对 RN 支持情况。
• 检查动态 class / style 是否使用了 {{}} 拼接字符串，统一改造为 wx:class / wx:style 指令绑定。
• 检查 <script> 中 selector 类 API 引用的节点是否声明空 wx:ref，未声明的须补齐。
• 对于无法等效实现的部分使用 模板条件编译（@mode / @_mode / mpxTagName@mode）进行平台隔离，并添加 todo 注释记录差异原因。

2. 脚本（script）适配改造

• 读取 逻辑能力参考 与 环境 API 参考，对 <script> 中的生命周期、构造选项、实例方法与环境 API 调用逐一核对 RN 支持情况。
• 平台直连 API（如 wx.xxx / my.xxx）统一替换为 mpx.xxx 接入 @mpxjs/api-proxy 抹平的实现。
• 涉及 selector 的脚本逻辑须改造为 #id / .class 写法，并在对应模板节点添加空 wx:ref。
• 对于 RN 平台不支持的脚本逻辑分支，使用 脚本条件编译 进行平台隔离，并添加 todo 注释记录差异原因。

3. 样式（style）适配改造

1. 展开嵌套选择器：对于 sass / less / stylus 等支持嵌套写法的预处理语言，先将 <style> 中的嵌套选择器展开铺平为传统选择器写法，便于后续兼容性判断。
   • Bad Example (嵌套未展开):

     .list {
       .item {
         color: red;
         &.active { color: blue; }
       }
     }
     

   • Good Example (嵌套已展开):

     .list .item { color: red; }
     .list .item.active { color: blue; }
     

2. 选择器适配改造：读取 样式开发最佳实践 · 选择器使用建议，将 RN 不支持的选择器改造为跨端兼容的单类等效实现，并同步更新 <template> 与 <script> 中的类名引用。
3. 样式属性适配改造：读取 样式能力参考 检查 <style>、<template>、<script> 中所有出现的样式属性的 RN 支持情况；读取 样式开发最佳实践 改造为跨端兼容的等效实现。
4. 原子类适配改造：项目已启用 UnoCSS 时，读取 Mpx2RN 原子 CSS 能力参考，检查模板中的工具类、variants、动态类提取与颜色透明度写法；将 RN 不支持的工具类改为支持的原子类组合或普通跨端样式。
5. 不可兼容部分使用条件编译：对无法跨端等效实现的选择器、样式属性或原子类，使用 样式条件编译 对整条规则进行最小包裹，保留在原平台输出产物中，添加 todo 注释记录差异原因。
   • Good Example (整条规则一并条件编译，避免空选择器):

     /* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
     /* todo: RN 不支持 ::-webkit-scrollbar 伪元素 */
     .scroll-view::-webkit-scrollbar { display: none; }
     /* @mpx-endif */
     

4. JSON 配置适配改造

• 读取 JSON 配置参考，检查 <script type="application/json"> 或 <script name="json"> 中所用字段在 RN 平台的支持情况。
• 对于平台差异较大的配置项，将 JSON 区块改写为 <script name="json"> 形式，借助 __mpx_mode__ 进行 配置条件编译。

5. 编译校验

完成上述改造后，使用本 skill 自带的编译校验脚本对修改后的 .mpx 文件进行真实编译校验（位于 skill 目录下的 scripts/compile-validate.js，不在宿主项目根目录下），参见下文 编译校验脚本。若校验失败，按错误分类回到对应步骤进行修正。

6. 检查与确认

按 SFC 各区块逐项核对，并确认条件编译与编译校验已收尾：

跨平台兼容

• 引入的「RN 支持但原平台不支持」的写法均已通过条件编译限定在 RN 输出；原平台原有写法已用条件编译保留，未因 RN 适配而被替换或删除。

模板（template）

• <template> 中使用的基础组件、属性、事件均在 模板能力参考 标注为 RN 支持，或已通过模板条件编译进行平台隔离；如用户通过 rnConfig.customBuiltInComponents 编译配置扩充拓展了基础组件能力，以用户说明为准。
• 动态 class / style 已改造为 wx:class / wx:style 指令，未在属性值内使用 {{}} 拼接。
• selector 类 API 引用的模板节点均已声明空 wx:ref 完成编译期映射。

脚本（script）

• <script> 中使用的生命周期、构造选项、实例方法与环境 API 均在 逻辑能力参考 与 环境 API 参考 标注为 RN 支持，或已通过脚本条件编译进行平台隔离；如用户通过 custom 配置扩充拓展了环境 API 能力，以用户说明为准。
• 平台直连 API（wx.xxx / my.xxx）已统一替换为 mpx.xxx；selector 类 API 仅使用 #id / .class 写法。
• 挂载到实例上的数据 key（props / data / computed / methods / <script setup> 的 return / inject 等）均未使用保留关键字 id / dataset / data。

样式（style）

• <style> 中不存在嵌套选择器写法。
• <style>、<template>、<script> 中使用的选择器和样式属性均在 样式能力参考 标注为 RN 支持，或已通过样式条件编译进行平台隔离。
• 项目启用 UnoCSS 时，模板中的工具类与 variants 均在 原子 CSS 能力参考 标注的 RN 支持范围内；动态类可被静态提取或已加入 safelist；颜色透明度未使用独立 *-opacity-* 组合。
• /*use rpx*/ / /*use px*/ 单位注释已保留。

JSON 配置

• <script type="application/json"> / <script name="json"> 中使用的字段均在 JSON 配置参考 标注为 RN 支持，或已通过配置条件编译进行平台隔离。

条件编译

• 不存在大面积连续条件编译，仅最小包裹不兼容片段。
• 样式条件编译处理后产物中不存在空选择器。
• 各个区块内的条件编译语法都符合规范，不存在误用（如在模板区块中使用 /* @mpx-if */ 注释语法等）。

本地校验

• 通过 编译校验脚本 真实编译校验。
• 通过本地环境 ESLint 校验（如 npx eslint path/to/component.mpx），无 lint 错误与警告。

任务二：创建符合 RN 跨端兼容规范的 Mpx 组件

输入

用户描述的组件需求，包括视图结构、交互、数据来源、目标平台范围、是否需要复用 React Native 原生组件 / Hooks 等。

输出

完整的 {name}.mpx 组件文件，结构包含 <template>、<script>、<style> 与 JSON 配置区块。代码须直接满足 通用约束与适配原则，避免新建后再走一轮适配改造。

任务流程

1. 设计阶段

• 与用户对齐需求要点：组件视图结构、props / 事件、数据流、目标平台、是否需要 RN 原生能力。
• 若组件性能敏感或需要复用 React Native 原生组件 / Hooks，读取 Mpx 与 RN 混合开发，确定平台隔离策略：
  • 平台差异较大：使用文件维度条件编译（hybrid-card.mpx / hybrid-card.ios.mpx），在独立文件中引入 react-native 依赖，避免原平台构建解析。
  • 局部差异较小：使用模板/属性维度条件编译（@mode / @_mode / mpxTagName@mode）隔离 RN 专属属性或少量节点。

2. 实施阶段

按 SFC 四个区块依次实现，全程遵循 通用约束与适配原则：

• <template>：读取 模板能力参考，仅选用 RN 支持的基础组件、属性与事件；动态样式类名绑定使用 wx:class / wx:style；selector 类 API 涉及节点声明空 wx:ref。
• <script>：读取 逻辑能力参考 与 环境 API 参考，仅使用 RN 支持的生命周期、构造选项与 API；统一通过 mpx.xxx 调用环境能力。
  • 优先使用组合式 API：新建组件优先使用 <script setup> 风格的组合式 API 编写逻辑，生命周期须在 <script setup> 顶层同步注册，详见 逻辑能力参考 · 组合式 API。
  • 状态管理优先使用 @mpxjs/pinia：新项目、新状态域或与组合式 API 协同时，使用 @mpxjs/pinia（Pinia 风格）；仅当工程已深度使用 @mpxjs/store（Vuex 风格）时继续维护沿用，避免同一业务域两套方案并存。详见 逻辑能力参考 · 状态管理。
• <style>：读取 样式能力参考 与 样式开发最佳实践，从一开始就使用单类选择器、Flex 布局、rpx 单位、hover-class 等跨端兼容写法；项目启用 UnoCSS 时再读取 Mpx2RN 原子 CSS 能力参考，只使用 RN 支持的工具类与 variants。
• JSON 配置：读取 JSON 配置参考，仅使用 RN 支持的字段；当需要分平台注册组件或差异化配置时，使用 <script name="json"> 形式动态生成。

3. 编译校验

使用本 skill 自带的编译校验脚本（位于 skill 目录下的 scripts/compile-validate.js，不在宿主项目根目录下）校验新建组件，参见下文 编译校验脚本。建议同时校验所有目标平台（如 --target=wx,ios,web），确保跨端兼容。

4. 检查与确认

复用 任务一 · 检查与确认 的清单，确认新建组件不引入任何 RN 不兼容写法。

编译校验脚本

脚本位置：编译校验脚本随本 skill 一同分发，位于 skill 目录下 的 scripts/compile-validate.js（即 <skill-root>/scripts/compile-validate.js），下文所有命令示例均使用 指向 skill 目录的路径调用该脚本，不要尝试在宿主项目根目录或 node_modules 中查找它。

该脚本基于宿主项目内安装的 @mpxjs/mpx-cli-service 进行真实编译校验：会自动从输入 .mpx 文件向上探测宿主项目根目录、加载工程编译配置、按指定 target 进行编译，并按 style / template / script / json / dependency / other 分类聚合错误与警告。改造或新建组件后建议作为强制环节运行。

命令行参数

退出码：0 校验通过；1 存在编译错误；2 运行期异常（如未找到 @mpxjs/mpx-cli-service）。

使用示例

下方示例中的 <skill-root> 表示本 skill 在宿主环境中的实际安装路径（例如 .agents/skills/mpx2rn、.claude/skills/mpx2rn 或 ~/.claude/skills/mpx2rn 等，以实际安装位置为准）；调用时使用该绝对路径，不要在宿主项目根目录下查找 scripts/compile-validate.js。

# 单组件、默认 target=ios
node <skill-root>/scripts/compile-validate.js src/components/foo.mpx

# 显式指定为页面（影响 entry 与 partialCompileRules 形态）
node <skill-root>/scripts/compile-validate.js src/pages/index.mpx --type=page --target=ios

# 跨端多目标校验
node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=wx,ios,web

# 输出结构化 JSON 便于二次处理
node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=ios --json

# 同时递归校验子组件（默认行为是仅校验目标自身）
node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=ios --no-ignore-sub-components

校验失败时按错误的 category 字段回到对应任务步骤定位与修正问题，再次运行直至通过。