# @capgo/capacitor-wechat 中文文档 规范地址：https://npmcn.com/package/%40capgo/capacitor-wechat/ 版本：8\.0\.56 npm 元数据更新时间：2026-11-02T13:03:06.202Z 中文译文更新时间：2026-11-09T15:22:18.946Z 软件包许可：MPL-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-wechat 原文对照：https://npmcn.com/package/%40capgo/capacitor-wechat/?lang=original 项目主页：https://capgo.app/docs/plugins/wechat/ 源码仓库：https://github.com/Cap-go/capacitor-wechat ## 关键信息（来自 npm 元数据） - 包体积（解压后）：153 kB，35 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：@capacitor/core \>=8\.0\.0 - 首次发布：2025-10-26T17:39:12.795Z - 最新版本发布：2026-11-02T13:03:05.900Z - 近 30 天下载量：2381（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：66（近 12 个月 58 个） ## 中文简介 WeChat SDK for Capacitor - 允许认证、共享、支付和小型程序 ## 安装 ```sh npm install @capgo/capacitor-wechat ``` 也可以使用：`pnpm add @capgo/capacitor-wechat`、`yarn add @capgo/capacitor-wechat`、`bun add @capgo/capacitor-wechat` ## README # 电容器-微声 在您的 Capacitor app 中加入 WeChat 登录, 共享, 支付和小型程序, 并使用 WeChat Open SDK 的官方程序 . [![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-wechat)](https://capgo.app/?ref=plugin_wechat) **队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚. ## [\*免费开始\*](https://capgo.app/register/?ref=plugin_wechat) 14天无限自由审判. 不需要信用卡 > 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_wechat) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-wechat` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-wechat到我的Capacitor app上,并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_wechat) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_wechat) ![@capgo/capacitor-wechat for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-wechat/main/assets/github-social-preview.png) ## 主要特点 - **设置**数字 : `initialize()` 用您的 WeChat 应用程序 ID 和 `isInstalled()` 检查应用程序. - **登录**数字 : `auth()` 运行 WeChat OAuth 流量. - **共享**数字 : `share()` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}聊天 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}时间和时间. - **付款**数字 : `sendPaymentRequest()` 为 WeChat 付费. - **小型方案和发票**数字 : `openMiniProgram()` 财务报告和审定财务报表 `chooseInvoice()`。 。 。 . - **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 在网上不可用. ## 文档 这里有最完整的医生: [https://capgo.app/docs/plugins/wechat/ (中文(简体) )](https://capgo.app/docs/plugins/wechat/) ## 兼容性 | 插件版本 | 电容兼容性 | 维护 | | --- | --- | --- | | 联合国 | 联合国 | ✅ | | 页:1 | 页:1 | 应要求 | | 页:1 | 页:1 | ❌ | | 页:1 | 页:1 | ❌ | > **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护. ## 安装 您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 : ```bash npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins ``` 然后使用下列提示: ```text Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-wechat` plugin in my project. ``` 如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令: ```bash npm install @capgo/capacitor-wechat npx cap sync ``` ## 配置 ### 电容配置 将您的 WeChat 证书添加到 `capacitor.config.ts` (或 `.json`) (中文(简体) ). 你可以在运行时通过呼叫来覆盖它们 `CapacitorWechat.initialize(...)`。 。 。 . ```ts const config: CapacitorConfig = { appId: 'com.example.app', appName: 'Example', webDir: 'dist', plugins: { CapacitorWechat: { appId: 'wx1234567890abcdef', universalLink: 'https://your-universal-link.example.com/' } } }; ``` ### iOS系统 在您的 `Info.plist`数字 : ```xml LSApplicationQueriesSchemes weixin weixinULAPI CFBundleURLTypes CFBundleTypeRole Editor CFBundleURLName weixin CFBundleURLSchemes YOUR_WECHAT_APP_ID ``` 你需要把 WeChat SDK 整合到您的iOS项目中. 将 WeChat SDK 添加到您的 `Podfile` 或从中下载 [WeChat 开放平台](https://developers.weixin.qq.com/doc/oplatform/en/Mobile_App/Access_Guide/iOS.html)。 。 。 . **重要内容:** iOS需要配置有效的通用链接. 你必须设置 `universalLink` 参数或者在您 `capacitor.config` (如上所示)或打电话时 `initialize()`. 没有有效的通用链接,该应用程序将在 WeChat SDK 初始化期间崩溃. 学习更多关于配置通用链接 [WeChat iOS 文档](https://developers.weixin.qq.com/doc/oplatform/en/Mobile_App/Access_Guide/iOS.html)。 。 。 . ### 机器人 插件传送 a `AndroidManifest.xml` 与 WeChat 的 Android 11+ 软件包可见度查询(`com.tencent.mm`) (中文(简体) ). 这需要用于 `isInstalled()` 编号 : `isWXAppInstalled()` 在Android 11和较新的工作。 如果您维持自定义的显示合并设置,请添加: ```xml ``` 在您的应用中加入 WeChat 回调活动 `AndroidManifest.xml`数字 : ```xml ``` 你得把WeChat SDK 纳入你的Android项目 将 WeChat SDK 依赖添加到您的 `build.gradle` 或从中下载 [WeChat 开放平台](https://developers.weixin.qq.com/doc/oplatform/en/Mobile_App/Access_Guide/Android.html)。 。 。 . 创建 `WXEntryActivity` 财务报告和审定财务报表 `WXPayEntryActivity` 在您的应用程序包中( e)`your.package.name.wxapi`) (中文(简体) ). 这两项活动应延长 `ee.forgr.plugin.capacitor_wechat.WechatResponseActivity` 因此插件可以从 WeChat 接收回调 : ```java package your.package.name.wxapi; import ee.forgr.plugin.capacitor_wechat.WechatResponseActivity; public class WXEntryActivity extends WechatResponseActivity {} public class WXPayEntryActivity extends WechatResponseActivity {} ``` 在您的应用程序列表中注册这些活动, 就像上面的片段( WeChat 既要求一般的 SDK + 报酬回调) . ## 设置 在使用任何 WeChat 功能之前, 您需要使用 WeChat App ID 注册您的应用程序 [WeChat 开放平台](https://open.weixin.qq.com/)。一旦你拿到证书,就把他们放进 `capacitor.config` 或打电话 `CapacitorWechat.initialize` 在打电话之前: ```ts import { CapacitorWechat } from '@capgo/capacitor-wechat'; await CapacitorWechat.initialize({ appId: 'wx1234567890abcdef', universalLink: 'https://your-universal-link.example.com/' }); ``` ## API 密码 - [`initialize(...)`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-initialize) - [`isInstalled()`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-isinstalled) - [`auth(...)`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-auth) - [`share(...)`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-share) - [`sendPaymentRequest(...)`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-sendpaymentrequest) - [`openMiniProgram(...)`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-openminiprogram) - [`chooseInvoice(...)`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-chooseinvoice) - [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-getpluginversion) - [接口](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-interfaces) 控制器 WeChat插件 - WeChat SDK集成,用于认证,共享,支付和小型程序. ### 初始化(...) ```typescript initialize(options: WechatInitializationOptions) => Promise ``` 以您的申请资格初始化 WeChat SDK . 您也可以在 `capacitor.config.ts` 下划线 `CapacitorWechat` 插件配置 。 调用此方法可以覆盖运行时的任何捆绑配置 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `[WechatInitializationOptions](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatinitializationoptions)` | \- 初始化选项,包括所需的 WeChat App ID | **自:** 1.1.0 国家 * * * ### 已安装( I) ```typescript isInstalled() => Promise<{ installed: boolean; }> ``` 请检查weChat app是否安装在设备上 . **回返情况:** `Promise<{ installed: boolean; }>` **自:** 1.0.0 (单位:千美元) * * * ### 认证(...) ```typescript auth(options: WechatAuthOptions) => Promise ``` 使用 WeChat OAuth 认证用户 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `[WechatAuthOptions](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatauthoptions)` | \- 包括范围在内的认证选项 | **回返情况:** `Promise<[WechatAuthResponse](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatauthresponse)>` **自:** 1.0.0 (单位:千美元) * * * ### 共享(...) ```typescript share(options: WechatShareOptions) => Promise ``` 分享内容给 WeChat. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `[WechatShareOptions](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatshareoptions)` | \- 分享包括类型、场景和内容在内的选项 | **自:** 1.0.0 (单位:千美元) * * * ### 发送付费请求(...) ```typescript sendPaymentRequest(options: WechatPaymentOptions) => Promise ``` 将支付请求发送给 WeChat Pay. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `[WechatPaymentOptions](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatpaymentoptions)` | \- 服务器的付款请求选项 | **自:** 1.0.0 (单位:千美元) * * * ### 打开Mini 程序(...) ```typescript openMiniProgram(options: WechatMiniProgramOptions) => Promise<{ extMsg?: string; }> ``` 开通微信小程序. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `[WechatMiniProgramOptions](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatminiprogramoptions)` | \- 包括用户名和路径在内的小型程序选项 | **回返情况:** `Promise<{ extMsg?: string; }>` **自:** 1.0.0 (单位:千美元) * * * ### 选择发票(...) ```typescript chooseInvoice(options: WechatInvoiceOptions) => Promise ``` 从 WeChat 选择发票 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `[WechatInvoiceOptions](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatinvoiceoptions)` | \- 发票选择方案 | **回返情况:** `Promise<[WechatInvoiceResponse](https://npmcn.com/package/%40capgo/capacitor-wechat/#readme-wechatinvoiceresponse)>` **自:** 1.0.0 (单位:千美元) * * * ### 获取 PluginVersion () ```typescript getPluginVersion() => Promise<{ version: string; }> ``` 获取本地 Capacitor 插件版本 . **回返情况:** `Promise<{ version: string; }>` **自:** 1.0.0 (单位:千美元) * * * ### 接口 #### Wechat 初始化选项 WeChat 初始化选项. | Prop | 类型 | 说明 | | --- | --- | --- | | **`appId`** | `string` | 需要 WeChat 应用程序 ID . | | **`universalLink`** | `string` | 与您的 WeChat 应用程序相联的 iOS 通用链接 . | #### WechatAuth 回复 WeChat认证响应. | Prop | 类型 | 说明 | | --- | --- | --- | | **`code`** | `string` | 授权代码以交换访问令牌. | | **`state`** | `string` | 如果请求中提供国家参数. | #### Wechat Auth 选项 WeChat 认证选项 . | Prop | 类型 | 说明 | | --- | --- | --- | | **`scope`** | `string` | OAuth范围. 仅对用户信息使用“ snsapi userinfo” 或仅对登录使用“ snsapi login” . | | **`state`** | `string` | CSRF 保护的可选状态参数. | #### Wechat 共享选项 WeChat 共享选项. | Prop | 类型 | 说明 | | --- | --- | --- | | **`scene`** | `number` | 分享场景:0=会话(聊天),1=时光线(时刻),2=最爱. | | **`type`** | `'text' | 'image' | 'link' | 'music' | 'video' | 'miniprogram'` | 共享类型:"text","image","link","music","video","miniprogram". | | **`text`** | `string` | 文本内容( 对于“ text” 类型) . | | **`title`** | `string` | 标题(用于"link","music","video","miniprogram"). | | **`description`** | `string` | 描述(用于"link","music","video","miniprogram"). | | **`link`** | `string` | 链接 URL (用于"link"类型). | | **`imageUrl`** | `string` | 图像 URL 或 base64 数据. | | **`thumbUrl`** | `string` | 缩略图 URL 或 Base64 数据(用于"link","music","video"等类型). | | **`mediaUrl`** | `string` | 音乐或视频 URL(用于"music","video"类型). | | **`miniProgramUsername`** | `string` | 迷你程序用户名(用于"迷你程序"类型). | | **`miniProgramPath`** | `string` | 迷你程序路由(用于"迷你程序"类型). | | **`miniProgramType`** | `number` | 迷你程序类型:0=放出,1=测试,2=预览(用于"迷你程序"类型). | | **`miniProgramWebPageUrl`** | `string` | 迷你程序网页 URL回落 (用于"迷你程序"类型). | #### Wechat Payment 选项 WeChat支付选项. | Prop | 类型 | 说明 | | --- | --- | --- | | **`partnerId`** | `string` | 合伙人身份证(商身份证). | | **`prepayId`** | `string` | 从统一的订单 API 预付ID. | | **`nonceStr`** | `string` | 随机弦. | | **`timeStamp`** | `string` | 时间戳. | | **`package`** | `string` | 包值,一般为"Sign=WXPay". | | **`sign`** | `string` | 签名. | #### WechatMini 方案选项 WeChat小程序选项. | Prop | 类型 | 说明 | | --- | --- | --- | | **`username`** | `string` | 迷你程序用户名(原始ID). | | **`path`** | `string` | 小型程序打开路径 . | | **`type`** | `number` | 迷你程序类型:0=放出,1=测试,2=预览. | #### Wechat 发票回复 WeChat发票回复. | Prop | 类型 | 说明 | | --- | --- | --- | | **`cards`** | `WechatInvoiceCard[]` | 选定卡片标识的组合 . | #### Wechat 发票卡 WeChat发票卡项目. | Prop | 类型 | 说明 | | --- | --- | --- | | **`cardId`** | `string` | 选中的卡标识符 . | | **`encryptCode`** | `string` | WeChat返回的加密代码. | #### Wechat 语音选项 WeChat 发票选项. | Prop | 类型 | 说明 | | --- | --- | --- | | **`appId`** | `string` | 应用识别码. | | **`signType`** | `string` | 签名类型. | | **`cardSign`** | `string` | 卡片签名. | | **`timeStamp`** | `string` | 时间戳. | | **`nonceStr`** | `string` | 随机弦. | ## 用法实例 ### 检查安装 ```typescript import { CapacitorWechat } from '@capgo/capacitor-wechat'; const checkWechat = async () => { const { installed } = await CapacitorWechat.isInstalled(); console.log('WeChat installed:', installed); }; ``` ### 认证 ```typescript const loginWithWechat = async () => { try { const { code } = await CapacitorWechat.auth({ scope: 'snsapi_userinfo', state: 'my_random_state' }); // Send code to your backend to exchange for access token const response = await fetch('https://yourapi.com/auth/wechat', { method: 'POST', body: JSON.stringify({ code }) }); const { access_token } = await response.json(); console.log('Access token:', access_token); } catch (error) { console.error('WeChat auth failed:', error); } }; ``` ### 共享内容 ```typescript // Share text const shareText = async () => { await CapacitorWechat.share({ scene: 0, // 0 = Chat, 1 = Moments, 2 = Favorite type: 'text', text: 'Hello from Capacitor WeChat!' }); }; // Share link const shareLink = async () => { await CapacitorWechat.share({ scene: 1, type: 'link', title: 'Check out this awesome app!', description: 'Built with Capacitor', link: 'https://capacitorjs.com', thumbUrl: 'https://capacitorjs.com/icon.png' }); }; ``` ### 付款 ```typescript const payWithWechat = async () => { // First, get payment parameters from your server const paymentParams = await fetchPaymentParamsFromServer(); try { await CapacitorWechat.sendPaymentRequest({ partnerId: paymentParams.partnerId, prepayId: paymentParams.prepayId, nonceStr: paymentParams.nonceStr, timeStamp: paymentParams.timeStamp, package: paymentParams.package, sign: paymentParams.sign }); console.log('Payment successful!'); } catch (error) { console.error('Payment failed:', error); } }; ``` ### 打开迷你程序 ```typescript const openMiniProgram = async () => { const { extMsg } = await CapacitorWechat.openMiniProgram({ username: 'gh_xxxxxxxxxxxxx', // Mini program original ID path: 'pages/index/index', type: 0 // 0 = Release, 1 = Test, 2 = Preview }); console.log('Mini program returned:', extMsg); }; ``` ## 重要说明 1. **微调 SDK**:插件通过CocoaPod来拉出官方的SDK(`WechatOpenSDK`)和"格拉德"(英语:`com.tencent.mm.opensdk:wechat-sdk-android-without-mta`) (中文(简体) ). 如果使用自定义的构建设置,请确保这些依赖性保持不变. 2. **应用程序注册**: 您必须在 [WeChat 开放平台](https://open.weixin.qq.com/) 获取App ID. 3. **通用链接(iOS)**: 对于iOS 13+,您需要配置WeChat召回的通用链接. 4. **后端集成**: 认证和支付功能需要后端集成,以交换令牌代码并准备支付参数. ## 解决问题 ### iOS: 启动时使用 NSException 程序崩溃 **问题:** 在 WeChat 插件装入 NSException 错误时立即应用崩溃 . **解决方案 :** 这通常发生在 `universalLink` 未配置或为空。 确保您设置 `universalLink` 在你身边 `capacitor.config` 或打电话时 `initialize()`数字 : ```typescript // In capacitor.config.ts plugins: { CapacitorWechat: { appId: 'wx1234567890abcdef', universalLink: 'https://your-domain.com/universal-link/' // Required for iOS! } } // Or in your app initialization await CapacitorWechat.initialize({ appId: 'wx1234567890abcdef', universalLink: 'https://your-domain.com/universal-link/' }); ``` 学习如何为 WeChat 建立通用链接 [WeChat iOS 文档](https://developers.weixin.qq.com/doc/oplatform/en/Mobile_App/Access_Guide/iOS.html)。 。 。 . ### iOS: 用 Wechat OpenSDK 构建错误 **问题:** 构建失败, 错误涉及缺少 Wechat OpenSDK 模块 . **解决方案 :** 确保通过CocoaPods适当安装了WeChat SDK. 运行 : ```bash cd ios/App pod install ``` ## 贷项 此插件的灵感来自 [线多瓦- plugin- wechat](https://github.com/xu-li/cordova-plugin-wechat) 并改编为Capacitor. ## 许可证 麻省理工学院 ## 捐款 见 [捐款额](https://npmcn.com/package/%40capgo/capacitor-wechat/CONTRIBUTING.md) 关于如何为此插件贡献的详细信息. ## 常见问题 ### @capgo/capacitor-wechat 是什么？ WeChat SDK for Capacitor - 允许认证、共享、支付和小型程序 ### 如何安装 @capgo/capacitor-wechat？ 在项目目录运行 npm install @capgo/capacitor-wechat，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @capgo/capacitor-wechat 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @capgo/capacitor-wechat 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @capgo/capacitor-wechat 可以商用吗？ @capgo/capacitor-wechat 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。 ### @capgo/capacitor-wechat 的下载量有多少？ 根据 npm 官方下载统计，@capgo/capacitor-wechat 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,381 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @capgo/capacitor-wechat 还在维护吗？ 最新版本 8\.0\.56 发布于 2026/11/02（7 天前）；至今共发布 66 个版本，其中过去 12 个月发布了 58 个；首次发布于 2025/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。