更新记录

1.0.6（2026-09-03） 下载此版本

• 修复 Android 正式包无法读取 static 等代码包资源作为分享素材的问题。
• 三端兼容 static/... 与 /static/... 写法；Android 正式包通过 AssetManager 读取 /android_asset/ 资源。

平台兼容性

uni-app x(5.24)

dyl-weixin 使用文档

dyl-weixin 是面向 uni-app x 的微信 OpenSDK 源码插件，统一提供微信登录、分享、打开微信、拉起微信小程序，以及接收微信启动参数等能力。

插件支持 Android、iOS 和 HarmonyOS，源码未加密，也不写死 AppID、Android 包名/签名、iOS Universal Link 或鸿蒙应用身份。将整个 uni_modules/dyl-weixin 目录复制到其他 uni-app x 项目后，只需完成新宿主 App 的配置，即可继续使用相同 API。

插件目录名和插件 ID 请保持为 dyl-weixin。复制到其他项目没有问题，但不要只修改目录名来制作另一份插件。

1. 支持范围

1.1 基础环境

1.2 功能兼容表

HarmonyOS 使用官方 @tencent/***_open_sdk 1.0.16。该版本没有提供音乐分享和收藏场景，调用时插件会进入 fail 回调，并返回 9010010。

2. 原生 SDK 依赖

插件已包含或声明以下原生依赖，业务项目无需手动复制 SDK 文件：

因为包含原生依赖，Android/iOS 调试必须重新制作并选择自定义基座；HarmonyOS 需要安装依赖后重新编译应用。标准基座不包含本插件的微信 SDK。

3. 安装与目录迁移

3.1 当前项目

插件位于：

uni_modules/dyl-weixin/
├─ package.json
├─ readme.md
├─ changelog.md
├─ templates/
└─ utssdk/
   ├─ interface.uts
   ├─ unierror.uts
   ├─ app-android/
   ├─ app-ios/
   └─ app-harmony/

3.2 复制到其他项目

1. 把完整的 dyl-weixin 目录复制到目标项目的 uni_modules 下。
2. 保持最终路径为 目标项目/uni_modules/dyl-weixin。
3. 在目标项目中配置微信 AppID、Universal Link，以及三个原生平台的宿主身份。
4. 重新制作自定义基座或重新编译原生应用。
5. 按本文的初始化示例调用 API。

3.3 复制后哪些会自动生效

最短迁移流程是：复制完整目录 → 修改业务配置常量 → 完成对应平台宿主配置 → 重新制作自定义基座/原生包 → 真机验证。uni_modules 插件不能替目标项目自动修改 pages.json、业务 manifest.json 或项目级鸿蒙配置。

4. 微信开放平台准备

使用 App 原生微信能力前，需要先在微信开放平台创建或配置移动应用，并获得以 wx 开头的移动应用 AppID。

请注意区分：

微信登录成功后插件只返回一次性 code。请把 code 发送到自己的服务端，由服务端换取 access token 和用户信息。不要把微信 AppSecret 写在 uvue 页面、UTS 插件或客户端配置中。

5. 统一业务配置

推荐把可变参数放在项目自己的配置文件，例如 config/app.uts：

/** 微信开放平台移动应用 AppID。 */
export const ***_APP_APPID : string = 'wx1234567890abcdef'

/** iOS Universal Link，结尾建议保留 /。Android 和 HarmonyOS 会忽略该值。 */
export const ***_APP_UNIVERSAL_LINK : string = 'https://example.com/applink/'

/** 微信小程序原始 ID，通常以 gh_ 开头。 */
export const ***_MP_APPID : string = 'gh_xxxxxxxxxxxx'

这种组织方式有两个好处：插件可以原样迁移，测试/正式环境也只需要替换业务配置。

6. Android 接入

6.1 微信开放平台配置

在微信开放平台填写目标 Android App 的：

• 应用包名，即最终 applicationId。
• 应用签名指纹。必须与实际安装包使用的签名一致。
• 移动应用 AppID。

调试包、自定义基座和正式包如果使用不同签名，需要以微信开放平台登记信息为准。包名或签名不一致时，常见表现是 sendReq 被拒绝、微信打开后没有回调，或登录/分享立即失败。

6.2 WXEntryActivity

插件已通过 Android Manifest 声明 Activity alias：

${applicationId}.wxapi.WXEntryActivity

它会自动跟随宿主 App 的 applicationId，无需在目标项目中复制 Java/Kotlin Activity，也无需修改插件源码。

插件也会自动声明 android.permission.INTERNET 和微信包可见性。如果目标项目已经通过其他微信插件声明 ${applicationId}.wxapi.WXEntryActivity，请只保留一套微信原生接入，避免 Manifest 合并冲突或回调被另一套插件截获。

6.3 构建

1. 在 HBuilderX 中配置目标 App 的 Android 包名和签名。
2. 重新制作包含 dyl-weixin 的自定义基座。
3. 在运行菜单中选择新制作的自定义基座。
4. 卸载手机中的旧基座后重新安装，避免仍然运行旧原生壳。

7. iOS 接入

iOS 除了 AppID，还必须正确配置 URL Scheme、Universal Link 和 Associated Domains。

7.1 微信开放平台配置

在微信开放平台填写目标 iOS App 的：

• Bundle ID。
• Universal Link。
• 移动应用 AppID。

这些值必须与最终签名安装包一致。

7.2 URL Scheme

在 HBuilderX 的 manifest.json 可视化界面中，进入“App 模块配置 / iOS App 配置 / URL Schemes”，添加移动应用 AppID，例如：

wx1234567890abcdef

如果项目使用自定义 iOS 原生配置，也可以把以下内容合并到项目级 Info.plist：

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>wx1234567890abcdef</string>
    </array>
  </dict>
</array>

插件自己的 Info.plist 已声明查询微信所需的 schemes，但不会写死业务 AppID。

dyl-weixin 不依赖 DCloud 的 uni-share 微信模块。若宿主项目的 manifest.json 已启用 uni-share.weixin，它可能再集成一份微信 SDK；建议同一安装包只保留一套微信原生 SDK，避免重复符号、SDK 版本冲突或回调归属不明确。

7.3 Associated Domains

在项目 manifest.json 的 iOS capabilities 中配置关联域名，例如：

applinks:example.com

这里填写域名，不包含 https:// 和路径。调用 useWeiXin 时传入的 universalLink 则应是完整 HTTPS 地址，例如：

https://example.com/applink/

7.4 AASA 文件

Universal Link 域名必须按 Apple 和微信开放平台要求部署 apple-app-site-association 文件。请确认：

• 使用 HTTPS，证书有效。
• 请求过程中没有 301/302 跳转。
• AASA 中的 Team ID、Bundle ID 和路径与应用一致。
• Universal Link 能在真实 iOS 设备上直接唤起 App。

7.5 构建

插件在 utssdk/app-ios/Libs/***OpenSDK 中内置官方 ***OpenSDK 2.0.7 的 Objective-C 静态库和头文件，不依赖 CocoaPods。不要在宿主项目或其他插件中再次引入 ***OpenSDK，否则会产生重复符号。修改 URL Scheme、Associated Domains 或原生依赖后，应重新制作自定义基座。

***OpenSDK 2.0.7 的 CocoaPods 包只包含 .a 和头文件，没有 Swift module。插件的 Swift 桥接代码不能写 import ***OpenSDK；HBuilderX 会把 app-ios/Libs 下的 Objective-C 头文件加入生成工程的桥接头。若以后升级 iOS SDK，请同时替换该目录中的 .a、三个 .h 文件和 EmbedResources/PrivacyInfo.xcprivacy。

8. HarmonyOS 接入

8.1 微信开放平台配置

在微信开放平台登记目标鸿蒙应用的包名、签名信息和移动应用 AppID。实际签名证书必须与登记信息一致。

8.2 module.json5

把插件附带的模板合并到项目级 harmony-configs/entry/src/main/module.json5。模板位置：

uni_modules/dyl-weixin/templates/harmony-configs/entry/src/main/module.json5

关键配置如下：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home",
              "wxentity.action.open"
            ]
          }
        ]
      }
    ],
    "querySchemes": [
      "weixin"
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

注意：

• action.system.home 必须保留，否则会破坏应用桌面入口。
• 增加 wxentity.action.open，用于微信回跳。
• querySchemes 配置 weixin。
• 不要添加 wxopensdk。
• 合并模板，不要直接覆盖项目中已有的 abilities、permissions 或其他业务配置。

8.3 EntryAbility 回调

插件已通过 UTSHarmony.onAppAbilityCreate 和 UTSHarmony.onAppAbilityNewWant 接收微信回调。HBuilderX 5.24+ 不需要手动修改 EntryAbility.ets。

若要接收微信冷启动/热启动携带的 extInfo，应在应用初始化阶段尽早创建插件实例并调用 launch()。当前实现只把收到的启动参数交给已经注册的监听器，不保证为稍后创建的页面长期缓存。

8.4 构建

插件会引入 @tencent/***_open_sdk 1.0.16。首次接入或依赖版本变化后，需要安装鸿蒙三方依赖，并使用已配置 DevEco Studio 工具链的 HBuilderX 重新编译应用。

9. 导入与初始化

在需要调用微信能力的 uvue/uts 文件中导入：

import {
  useWeiXin,
  type WeiXinUtils,
  type UseWeiXinOptions,
  type LoginOptions,
  type NavigateToMiniProgramOptions,
  type ShareOptions,
  type LaunchFromWeiXinOptions
} from '@/uni_modules/dyl-weixin'

import {
  ***_APP_APPID,
  ***_APP_UNIVERSAL_LINK,
  ***_MP_APPID
} from '@/config/app.uts'

初始化参数：

初始化：

const weixinOptions : UseWeiXinOptions = {
  appId: ***_APP_APPID,
  universalLink: ***_APP_UNIVERSAL_LINK,
  success: (res) : void => {
    console.log('微信 SDK 初始化成功：' + res.errMsg)
  },
  fail: (err) : void => {
    console.error('微信 SDK 初始化失败：' + err.errCode.toString() + ' ' + err.errMsg)
  },
  complete: (res) : void => {
    console.log('微信 SDK 初始化结束')
  }
}

const wxUtils : WeiXinUtils = useWeiXin(weixinOptions)

建议在页面或业务服务初始化阶段创建一次实例并复用，不要在每次点击按钮时反复初始化。同一时刻也不要并发发起多次登录或分享请求。

初始化 success 的含义是插件已创建/注册微信 SDK 对象并接受当前配置，不等于微信开放平台已经验证了包名、签名、Bundle ID 或 Universal Link。最终身份是否匹配，要以真机发起登录、分享并成功收到微信回调为准。HarmonyOS 当前在 SDK 对象创建成功后即返回初始化成功，尤其需要通过真实请求验证配置。

如果同一代码文件还要编译到 Web 或小程序，请用 uni-app x 条件编译把插件导入和 App 调用限制在 APP 平台范围内。

// #ifdef APP
import {
  useWeiXin,
  type WeiXinUtils,
  type UseWeiXinOptions
} from '@/uni_modules/dyl-weixin'
// #endif

10. API 总览

interface WeiXinUtils {
  isInstalled() : boolean
  openApp() : void
  navigateToMiniProgram(options : NavigateToMiniProgramOptions) : void
  login(options : LoginOptions) : void
  share(options : ShareOptions) : void
  launch(options : LaunchFromWeiXinOptions) : void
}

11. isInstalled 判断微信是否安装

const installed : boolean = wxUtils.isInstalled()
if (installed == false) {
  uni.showToast({
    title: '请先安装微信',
    icon: 'none'
  })
}

返回 true 表示当前系统能够识别微信客户端。该结果不代表微信开放平台的包名、签名或 Universal Link 一定配置正确。

12. openApp 打开微信

if (wxUtils.isInstalled()) {
  wxUtils.openApp()
}

openApp() 没有回调。需要提示未安装时，应先调用 isInstalled()。

13. login 微信登录

13.1 参数

13.2 示例

const loginOptions : LoginOptions = {
  scope: 'snsapi_userinfo',
  state: 'login_state_20260902',
  success: (res) : void => {
    console.log('微信授权 code：' + res.code)
    console.log('微信返回 state：' + res.state)
    // 把 res.code 发送到自己的服务端换取用户信息。
  },
  fail: (err) : void => {
    console.error('微信登录失败：' + err.errCode.toString() + ' ' + err.errMsg)
  },
  complete: (res) : void => {
    console.log('微信登录流程结束')
  }
}

wxUtils.login(loginOptions)

success 的关键字段：

14. navigateToMiniProgram 拉起小程序

14.1 参数

14.2 示例

const miniProgramOptions : NavigateToMiniProgramOptions = {
  appId: ***_MP_APPID,
  path: '/pages/index/index?source=app',
  envVersion: 'release',
  extraData: {
    source: 'dyl-weixin'
  },
  success: (res) : void => {
    console.log(res.errMsg)
  },
  fail: (err) : void => {
    console.error(err.errCode.toString() + ' ' + err.errMsg)
  }
}

wxUtils.navigateToMiniProgram(miniProgramOptions)

此 API 的 success 表示微信 OpenSDK 已接受请求，不代表用户一定完成了小程序内的后续业务。

15. share 分享

15.1 公共参数

ShareOptions 类型中还保留了 openCustomerServiceChat、corpid、customerUrl 三个兼容字段，但当前 Android、iOS、HarmonyOS 实现都没有把它们传给原生 SDK，不能据此打开企业微信客服会话。业务代码暂时不要依赖这三个字段。

类型专用参数：

分享场景：

15.2 文本分享

const options : ShareOptions = {
  type: 'text',
  text: '来自 dyl-weixin 的文本分享',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

15.3 图片分享

const options : ShareOptions = {
  type: 'image',
  imageUrl: 'https://example.com/static/share.jpg',
  thumb: 'https://example.com/static/share-thumb.jpg',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

imageUrl 和 thumb 可以使用 HTTPS 网络地址或 uni-app x 可访问的本地路径。网络素材下载失败会返回网络/素材错误；本地文件无法读取会返回文件错误。

15.4 图文分享

const options : ShareOptions = {
  type: 'imageText',
  title: '图文标题',
  summary: '图文摘要',
  imageUrl: 'https://example.com/static/share.jpg',
  thumb: 'https://example.com/static/share-thumb.jpg',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

15.5 网页分享

const options : ShareOptions = {
  type: 'webpage',
  title: '网页标题',
  summary: '网页摘要',
  webpageUrl: 'https://example.com/article/1001',
  thumb: 'https://example.com/static/share-thumb.jpg',
  scene: 'timeline',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

15.6 小程序卡片分享

const options : ShareOptions = {
  type: 'miniProgram',
  title: '打开小程序',
  summary: '从 App 分享的小程序卡片',
  webpageUrl: 'https://example.com/fallback',
  thumb: 'https://example.com/static/mini-program-thumb.jpg',
  miniProgramId: ***_MP_APPID,
  miniProgramPath: '/pages/index/index?source=share',
  envVersion: 'release',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

小程序卡片建议同时提供 miniProgramId、webpageUrl、thumb 和 title。miniProgramId 同样是以 gh_ 开头的小程序原始 ID。

15.7 视频分享

const options : ShareOptions = {
  type: 'video',
  title: '视频标题',
  summary: '视频摘要',
  videoUrl: 'https://example.com/video/1001',
  thumb: 'https://example.com/static/video-thumb.jpg',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

15.8 音乐分享

const options : ShareOptions = {
  type: 'music',
  title: '音乐标题',
  summary: '音乐摘要',
  musicUrl: 'https://example.com/music/detail/1001',
  musicDataUrl: 'https://example.com/static/music.mp3',
  thumb: 'https://example.com/static/music-thumb.jpg',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

音乐分享仅支持 Android 和 iOS。HarmonyOS 调用会返回 9010010。

15.9 文件分享

const options : ShareOptions = {
  type: 'file',
  title: '对账单',
  summary: '2026 年 9 月对账单',
  filePath: '/storage/emulated/0/Download/report.pdf',
  fileExtension: 'pdf',
  thumb: 'https://example.com/static/file-thumb.png',
  scene: 'session',
  success: (res) : void => console.log(res.errMsg),
  fail: (err) : void => console.error(err.errMsg)
}

wxUtils.share(options)

本地文件路径必须是当前 App 有权读取的路径。Android 分区存储、iOS 沙盒和 HarmonyOS 沙盒规则不同，推荐先把文件下载或复制到应用可访问的临时/文档目录，再传给插件。

15.10 分享类型与必需字段

上表是建议业务统一遵循的跨平台契约。各原生 SDK 对空标题、空缩略图等边界的容忍度不同；不要因为某个平台偶尔能发送缺字段的对象，就省略通用必需字段。

15.11 素材路径、网络地址和大小限制

Android 是最需要注意的平台：即使 imageUrl 是 OSS/HTTPS 地址，当前实现仍会先下载整张图片，再把二进制放进发往微信的 Binder 请求。因此“把图片传到 OSS”只能解决本地路径和访问权限问题，不能规避 TransactionTooLargeException。海报分享建议在服务端或客户端先生成专用分享图，经验上先压到约 300KB 以内再调用；实际可用上限还会受标题、缩略图、系统和微信版本影响。

file 分享在 Android 也会把完整文件读成字节，虽然插件有基础上限校验，Binder 往往会在到达该上限之前失败，因此不适合分享大文件。iOS/HarmonyOS 的传递方式不同，也不应把“某一端能发”当作三端统一保障。

路径规则：HTTP/HTTPS 地址直接作为网络素材处理；file://、Android content:// 等原生 URI 会按平台处理；普通相对路径会转换为当前应用可访问的绝对路径。项目代码包资源支持 static/logo.png 与 /static/logo.png 两种写法，Android 正式包中的资源会从 APK assets 读取。跨项目迁移后不要复用另一个 App 的沙盒绝对路径。

16. launch 接收微信启动参数

launch 用于取得微信回跳或通过微信启动 App 时携带的扩展信息。

建议在应用启动阶段尽早注册：

const launchOptions : LaunchFromWeiXinOptions = {
  success: (res) : void => {
    console.log('微信启动参数：' + res.extInfo)
  },
  complete: (res) : void => {
    console.log('启动参数处理结束')
  }
}

wxUtils.launch(launchOptions)

如果本次启动不是来自微信，不会触发有效的 extInfo 回调。LaunchFromWeiXinOptions.fail 是为 API 兼容和后续扩展保留的字段，当前三端实现只在收到微信启动请求时触发 success 与 complete。不要把 launch 当作登录或分享结果回调；登录和分享结果仍由对应 API 的回调返回。

17. 回调结构

17.1 成功结果

type SuccessCallbackResult = {
  errSubject : string
  statusCode : number
  state : string
  code : string
  lang : string
  country : string
  errMsg : string
}

不同 API 只会填充相关字段，其余字符串字段可能为空。

17.2 启动结果

type SuccessLaunchResult = {
  errMsg : string
  extInfo : string
}

17.3 失败结果

失败对象实现 IUniError，常用字段为：

complete 会在 success 或 fail 之后执行。业务逻辑应以 success/fail 为准，complete 适合关闭 loading 等收尾工作。

还要区分两类“成功”：navigateToMiniProgram 的 success 表示 OpenSDK 已接受拉起请求；登录/分享的 success 则来自微信回调。分享回调仍是客户端 SDK 对本次请求的结果，不应替代服务端业务确认、订单状态或奖励发放依据。

18. 错误码

以下是当前实现会重点返回的错误码：

接口中的其他错误码为后续能力和兼容迁移预留，业务代码不要只依赖某一个错误码判断所有失败场景。

统一错误处理示例：

fail: (err) : void => {
  if (err.errCode == 9010002) {
    uni.showToast({ title: '请先安装微信', icon: 'none' })
    return
  }
  if (err.errCode == 9010005 || err.errCode == 9010014) {
    return
  }
  uni.showToast({ title: err.errMsg, icon: 'none' })
}

19. 自定义基座说明

出现以下任一变化后，都应重新制作基座或重新打原生包：

• 第一次添加 dyl-weixin。
• 修改插件 Android/iOS/HarmonyOS 原生代码。
• 修改原生 SDK 版本。
• 修改 Android 包名或签名。
• 修改 iOS URL Scheme、Associated Domains、Bundle ID 或 Universal Link。
• 修改 HarmonyOS module.json5、包名或签名。

仅修改页面 UTS/uvue 业务代码通常可以热更新；但标准基座和旧自定义基座不会自动获得新原生类。

20. 从 lime-weixin 迁移

原错误：

java.lang.NoClassDefFoundError:
Failed resolution of: Luts/sdk/modules/limeWeixin/UseWeiXinOptions;

表示运行时基座中没有旧插件生成的原生类型。迁移步骤：

1. 将业务导入改为 @/uni_modules/dyl-weixin。
2. 保持类型名 UseWeiXinOptions、ShareOptions 等不变。
3. 把 AppID、Universal Link、小程序原始 ID 放到业务配置文件。
4. 完成 Android/iOS/HarmonyOS 宿主配置。
5. 重新制作并选择包含新插件的自定义基座。
6. 卸载旧 App 后重新安装测试。

新插件 Android 生成包名为：

uts.sdk.modules.dylWeixin

如果错误栈仍然出现 uts.sdk.modules.limeWeixin，说明仍有旧导入、缓存构建产物或设备上仍安装着旧基座。

21. 常见问题

21.1 初始化回调失败

• 确认传入的是移动应用 AppID，而不是小程序 AppID。
• Android 检查 applicationId 和签名。
• iOS 检查 Bundle ID、URL Scheme、Universal Link 和 AASA。
• HarmonyOS 检查包名、签名、wxentity.action.open 和 querySchemes。

21.2 点击登录或分享没有任何回调

• 确认运行的是最新自定义基座，不是标准基座或旧基座。
• 不要并发调用多次 login 或 share。
• Android 检查 ${applicationId}.wxapi.WXEntryActivity 是否进入最终 Manifest。
• iOS 用真机验证 Universal Link，并检查 URL Scheme。
• HarmonyOS 检查项目级 module.json5 是否已合并模板。

21.3 微信能打开，但请求失败

这通常是宿主 App 身份不匹配，而不是“微信未安装”。检查开放平台登记的包名、Bundle ID、应用签名、Universal Link 和当前安装包是否完全一致。

21.4 网络图片或文件分享失败

• 优先使用 HTTPS。
• 确认 URL 无登录态或防盗链限制。
• 确认响应是真实图片/文件，而不是 HTML 错误页。
• 控制素材大小，缩略图尽量使用体积较小的 JPG/PNG。
• 本地文件先确认路径存在且 App 有读取权限。
• Android 网络图片会被下载为完整字节后发送给微信，OSS 地址不能绕过 Binder 大小限制；出现 TransactionTooLargeException 时必须压缩主图，而不只是更换 URL。

21.5 iOS 本地编译找不到微信 SDK

依次检查：

1. utssdk/app-ios/Libs/***OpenSDK 下存在 lib***OpenSDK.a、WXApi.h、WXApiObject.h 和 ***AuthSDK.h。
2. DYLWeixinIOSBridge.swift 中没有 import ***OpenSDK。官方 2.0.7 静态包不提供可直接导入的 Swift module。
3. utssdk/app-ios/config.json 中没有再次声明 dependencies-pods/***OpenSDK。
4. 宿主项目和其他原生插件没有再次集成微信 iOS SDK；同一 App 只能保留一份，否则可能出现重复符号或版本冲突。
5. 删除旧自定义基座并重新云打包。原生 SDK 或 Swift 桥接代码变更不会进入已经安装的旧基座。

21.6 HarmonyOS 无法编译

确认 HBuilderX 已配置可用的 DevEco Studio 工具链，并完成 ohpm 依赖安装。Windows 上仅做 UTS 语法生成不能替代完整的鸿蒙原生构建验证。

21.7 选择“留在微信”后，手动返回 App 无回调

Android 端从 1.0.1、iOS 和 HarmonyOS 端从 1.0.2 开始处理此场景：如果请求已离开宿主 App，但恢复到宿主 App 后仍未收到微信 OpenSDK 响应，插件会结束本次请求，并按顺序触发：

1. fail：errCode 为 9010004，表示“已返回宿主 App，但没有收到微信结果”。
2. complete：保证业务侧可以关闭 loading、恢复按钮状态并再次发起请求。

9010004 只表示微信没有回传可判定的结果，不能当作分享成功。账号受限、微信端拒绝处理、选择留在微信后手动切回等情况，都可能导致没有标准回调；如果微信明确回传错误，插件仍优先返回微信的实际错误信息。

升级后必须重新制作并安装对应平台的自定义基座/原生应用，旧安装包仍包含旧版原生桥接代码。

22. 可移植性边界

dyl-weixin 是可复制、可二次修改、源码未加密的公共本地插件，但当前没有自动发布到 DCloud 插件市场。

可随插件复制的内容：

• 统一 UTS API 和类型。
• Android/iOS/HarmonyOS 原生桥接代码。
• Android、HarmonyOS SDK 依赖声明，以及插件内置的 iOS 官方静态 SDK。
• 鸿蒙宿主配置模板。
• 本使用文档。

每个宿主 App 必须单独配置的内容：

• 微信开放平台移动应用 AppID。
• Android 包名与签名。
• iOS Bundle ID、URL Scheme、Universal Link、Associated Domains 和 AASA。
• HarmonyOS 包名、签名和项目级 module.json5。
• 小程序原始 ID。

这些配置属于目标 App 的身份，不能安全地写死在通用插件中。

22.1 测试页不属于插件 API

当前项目的综合测试页位于 pages/debug/weixin-test.uvue，它是宿主项目页面，不在 uni_modules/dyl-weixin 内。复制插件到其他项目时，测试页不会自动跟随；如需使用，应一并复制页面、检查其中的业务常量/素材地址，并在目标项目 pages.json 中注册。正式业务只依赖插件目录和本文 API，不依赖该测试页。

目标项目的 pages.json 可增加：

{
  "path": "pages/debug/weixin-test",
  "style": {
    "navigationBarTitleText": "微信 SDK 调试"
  }
}

该页面用于真机逐项验证安装检测、打开微信、登录、拉起小程序、各类分享和启动参数回调。页面中的 AppID、Universal Link、小程序原始 ID 应继续从目标项目配置读取，不要重新写死在测试页中。

23. 发布前检查清单

• [ ] uni_modules/dyl-weixin 目录完整。
• [ ] 业务代码只从 @/uni_modules/dyl-weixin 导入。
• [ ] 移动应用 AppID 正确。
• [ ] 小程序调用使用 gh_ 开头的原始 ID。
• [ ] Android 包名和正式签名已在微信开放平台登记。
• [ ] iOS Bundle ID、URL Scheme、Universal Link、Associated Domains、AASA 全部一致。
• [ ] HarmonyOS 已合并 wxentity.action.open、querySchemes: ["weixin"] 和网络权限。
• [ ] 已重新制作并选择最新自定义基座。
• [ ] Android 真机完成登录、分享和微信回跳测试。
• [ ] iOS 真机完成登录、分享和 Universal Link 回跳测试。
• [ ] HarmonyOS 真机完成登录、分享和 onAppAbilityNewWant 回跳测试。
• [ ] 服务端已实现用微信登录 code 换取用户凭证，客户端没有 AppSecret。

24. 相关资料

• uni-app x uni_modules 插件规范
• uni-app x UTS 插件开发
• UTSiOSHookProxy
• uni-app x HarmonyOS UTS 插件开发
• uni-app x iOS manifest 配置
• ***OpenSDK CocoaPods 规格（用于核对官方版本与系统依赖）
• 微信开放平台