开始使用

最后更新：2026/06/11

目录

-   [安装](https://developer.work.weixin.qq.com/document/path/90514/#%E5%AE%89%E8%A3%85)
-   [接口鉴权](https://developer.work.weixin.qq.com/document/path/90514/#%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83)
-         [调用要求](https://developer.work.weixin.qq.com/document/path/90514/#%E8%B0%83%E7%94%A8%E8%A6%81%E6%B1%82)
-         [企业身份注册](https://developer.work.weixin.qq.com/document/path/90514/#%E4%BC%81%E4%B8%9A%E8%BA%AB%E4%BB%BD%E6%B3%A8%E5%86%8C)
-         [应用身份注册](https://developer.work.weixin.qq.com/document/path/90514/#%E5%BA%94%E7%94%A8%E8%BA%AB%E4%BB%BD%E6%B3%A8%E5%86%8C)
-   [接口约定](https://developer.work.weixin.qq.com/document/path/90514/#%E6%8E%A5%E5%8F%A3%E7%BA%A6%E5%AE%9A)
-   [开发环境快速接入](https://developer.work.weixin.qq.com/document/path/90514/#%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E5%BF%AB%E9%80%9F%E6%8E%A5%E5%85%A5)
-   [旧版jweixin迁移](https://developer.work.weixin.qq.com/document/path/90514/#%E6%97%A7%E7%89%88jweixin%E8%BF%81%E7%A7%BB)
-         [迁移指南](https://developer.work.weixin.qq.com/document/path/90514/#%E8%BF%81%E7%A7%BB%E6%8C%87%E5%8D%97)

## [](https://developer.work.weixin.qq.com/document/path/90514/#%E5%AE%89%E8%A3%85)安装

企业微信JS-SDK提供了 npm 和 cdn 两种引入途径。

1.  通过 npm 引入  
    
    ```bash
    npm install @wecom/jssdk
    ```
    
      
    安装完成后即可在应用中使用 SDK：  
    
    ```js
    import * as ww from '@wecom/jssdk'
    ```
    
2.  通过 script 标签引入  
    
    ```html
    <script src="https://wwcdn.weixin.qq.com/node/wework/wwopen/js/wecom-jssdk-2.4.0.js"></script>
    ```
    
      
    安装完成后，SDK 会在 window 上定义 ww 对象：  
    
    ```html
    <script>
      alert(ww.SDK_VERSION)
    </script>
    ```
    

## [](https://developer.work.weixin.qq.com/document/path/90514/#%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83)接口鉴权

### [](https://developer.work.weixin.qq.com/document/path/90514/#%E8%B0%83%E7%94%A8%E8%A6%81%E6%B1%82)调用要求

-   所有的JS接口只能在企业微信应用的可信域名下调用(包括子域名)，且可信域名必须有ICP备案且在管理端验证域名归属。
-   验证域名归属的方法在企业微信的管理后台“我的应用”里，进入应用，设置应用可信域名。  
    
-   在调用 JSAPI 前，需要先通过 ww.register 注册当前页面的身份信息。身份信息分为两种：  
    1) 企业身份与权限，通过企业签名获得。  
    2) 应用（自建/待开发/第三方应用等）身份与权限，通过应用签名获得。  
    使用者可根据具体调用的JSAPI所要求的身份权限进行注册即可，应用身份权限 > 企业身份权限。

### [](https://developer.work.weixin.qq.com/document/path/90514/#%E4%BC%81%E4%B8%9A%E8%BA%AB%E4%BB%BD%E6%B3%A8%E5%86%8C)企业身份注册

```js
ww.register({
  corpId: 'ww7ca4776b2a70000',       // 必填，当前用户企业所属企业ID
  jsApiList: ['getExternalContact'], // 必填，需要使用的JSAPI列表
  getConfigSignature                 // 必填，根据url生成企业签名的回调函数
})

async function getConfigSignature(url) {
  // 根据 url 生成企业签名
  // 生成方法参考 https://developer.work.weixin.qq.com/document/14924
  return { timestamp, nonceStr, signature }
}
```

在注册应用身份信息时，开发者需要提供对应的签名函数。该函数需要根据当前页面的 URL 和应用的 Secret 等信息生成 JS-SDK 签名并返回相关信息。详见 [JS-SDK 签名算法](https://developer.work.weixin.qq.com/document/path/90514/#14924)。

**注意：**

-   **参数中的回调函数调用时机由 JSSDK 自行控制，开发者无需关心具体调用顺序**
-   用于生成签名的 jsapi\_ticket 属于敏感信息，请在服务端完成签名操作

### [](https://developer.work.weixin.qq.com/document/path/90514/#%E5%BA%94%E7%94%A8%E8%BA%AB%E4%BB%BD%E6%B3%A8%E5%86%8C)应用身份注册

应用在原有企业身份信息的基础上，需要额外提供应用身份信息（原 agentConfig）：

```js
ww.register({
  corpId: 'ww7ca4776b2a70000',       // 必填，当前用户企业所属企业ID
  agentId: 1000247,                  // 必填，当前应用的AgentID
  jsApiList: ['getExternalContact'], // 必填，需要使用的JSAPI列表
  getConfigSignature,                // 必填，根据url生成企业签名的回调函数
  getAgentConfigSignature            // 必填，根据url生成应用签名的回调函数
})

async function getConfigSignature(url) {
  // 根据 url 生成企业签名
  // 生成方法参考 https://developer.work.weixin.qq.com/document/14924
  return { timestamp, nonceStr, signature }
}

async function getAgentConfigSignature(url) {
  // 根据 url 生成应用签名，生成方法同上，但需要使用应用的 jsapi_ticket
  return { timestamp, nonceStr, signature }
}
```

应用在原有签名函数的基础上，需要额外提供应用的AgentID以及应用签名函数。和原有的签名函数不同，应用签名函数需要使用应用的 jsapi\_ticket。见 [获取应用 jsapi\_ticket](https://developer.work.weixin.qq.com/document/path/90514/#14924/%E8%8E%B7%E5%8F%96%E5%BA%94%E7%94%A8-jsapi-ticket)。

**注意：用于生成签名的 jsapi\_ticket 属于敏感信息，请在服务端完成签名操作。**

## [](https://developer.work.weixin.qq.com/document/path/90514/#%E6%8E%A5%E5%8F%A3%E7%BA%A6%E5%AE%9A)接口约定

在调用 ww.register 后，页面可以立刻调用其他 JSAPI，JS-SDK 内部会自行处理注册身份信息的时序。这里约定两种通用的 JS 接口调用形式：

**1\. 命令接口：**

```js
ww.方法名({
  参数: xxx,
  success(result) {
    // 成功回调，result.errMsg 固定格式为“方法名:ok”
  },
  fail(result) {
    // 失败回调，通过 result.errMsg 查看失败详情
  },
  complete(result) {
    // 完成回调，无论调用成功还是失败，都会回调该方法
  }
})
```

**2\. 事件接口：**

```js
ww.on事件名(event => {
  // 事件发生时回调
})
```

另外所有命令接口均会返回 promise，开发者也可以通过 promise 的回调获取调用结果：

```js
const { errMsg, userIds } = await ww.selectExternalContact()
// errMsg === 'selectExternalContact:ok'
```

## [](https://developer.work.weixin.qq.com/document/path/90514/#%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E5%BF%AB%E9%80%9F%E6%8E%A5%E5%85%A5)开发环境快速接入

为方便开发者在**开发环境**快速接入，JS-SDK 提供了 getSignature 方法，开发者可以通过内联 jsapi\_ticket 在页面上生成 JSAPI 签名：

```js
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// 该代码仅用于开发环境快速接入，请勿在生产环境对外暴露JSAPI_TICKET
// Ticket有效期为2个小时，过期后请手动更换
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
const JSAPI_TICKET = 'sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg '

ww.register({
  corpId: 'ww7ca4776b2a70000',
  jsApiList: ['selectExternalContact'],
  getConfigSignature() {
    return ww.getSignature(JSAPI_TICKET)
  }
})

// 调用 register 后可以立刻调用其他 JS 接口
ww.selectExternalContact({
  success(res) {
    alert(JSON.stringify(res))
  }
})
```

jsapi\_ticket 的获取方法可以参考[获取企业 jsapi\_ticket](https://developer.work.weixin.qq.com/document/path/90514/#14924/%E8%8E%B7%E5%8F%96%E4%BC%81%E4%B8%9A-jsapi-ticket)和[获取应用 jsapi\_ticket](https://developer.work.weixin.qq.com/document/path/90514/#14924/%E8%8E%B7%E5%8F%96%E5%BA%94%E7%94%A8-jsapi-ticket)，在开发阶段我们也可以通过以下命令快速获取：

```bash
# CORPID、SECRET为占位符，请自行填入真实的企业ID和应用Secret
npx wwutil ticket CORPID SECRET
```

## [](https://developer.work.weixin.qq.com/document/path/90514/#%E6%97%A7%E7%89%88jweixin%E8%BF%81%E7%A7%BB)旧版jweixin迁移

新版的wecom-jssdk.js中，我们提供了完全的Typescript类型支持，npm引入等新特性。未来企业微信中新功能接口也将基于wecom-jssdk进行更新升级。如果你的应用正在使用旧版 jweixin-1.2.0.js进行接口调用，我们强烈建议进行升级。

### [](https://developer.work.weixin.qq.com/document/path/90514/#%E8%BF%81%E7%A7%BB%E6%8C%87%E5%8D%97)迁移指南

**非兼容性的改变：**  
1、wx.config, wx.agentConfig 需改为使用ww.register进行身份注册。  
2、ww.register方法，开发者无需关注ready等注册状态，SDK内部会自动处理相关函数回调。

兼容性改变：  
ww.invoke方法，ww.on方法 均兼容旧版的wx.invoke，wx.on方法，可以直接进行替换。

**以下为旧版 jweixin-1.2.0.js 的接入和使用方式。**

**步骤一：引入JS文件**

在需要调用JS接口的页面引入如下JS文件：[https://res.wx.qq.com/open/js/jweixin-1.2.0.js](https://res.wx.qq.com/open/js/jweixin-1.2.0.js)

```javascript
<script src="https://res.wx.qq.com/open/js/jweixin-1.2.0.js"></script>
```

> 为支持微信插件（原企业号）功能，请引用此文件。原企业微信的js文件在微信插件不生效。  
> jweixin-1.6.0 版本企业微信客户端暂不支持。

**步骤二：通过config接口注入权限验证配置**

> 所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用（同一个url仅需调用一次，对于变化url的SPA（single-page application）的web app可在每次url变化时进行调用）。

```javascript
wx.config({
    beta: true,// 必须这么写，否则wx.invoke调用形式的jsapi会有问题
    debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
    appId: '', // 必填，企业微信的corpID，必须是本企业的corpID，不允许跨企业使用
    timestamp: '', // 必填，生成签名的时间戳
    nonceStr: '', // 必填，生成签名的随机串
    signature: '',// 必填，签名，见 附录-JS-SDK使用权限签名算法
    jsApiList: [] // 必填，需要使用的JS接口列表，凡是要调用的接口都需要传进来
});
```

生成签名算法详见：[附录-JS-SDK使用权限签名算法](https://developer.work.weixin.qq.com/document/path/90514/#14924)  
**步骤三：通过ready接口处理成功验证**

```javascript
wx.ready(function(){
    // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});
```

**步骤四：通过error接口处理失败验证**

```javascript
wx.error(function(res){
    // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
});
```

**接口调用说明**

所有接口通过wx对象(也可使用jWeixin对象)来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：

1.  success：接口调用成功时执行的回调函数。
2.  fail：接口调用失败时执行的回调函数。
3.  complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。
4.  cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。
5.  trigger: 监听Menu中的按钮点击时触发的方法，该方法仅支持Menu中的相关接口。

> 不要尝试在 trigger 中使用 Ajax 异步请求修改本次分享的内容，因为客户端分享操作是一个同步操作，这时候使用 Ajax 的回包会还没有返回。

以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性err\_msg，其值格式如下：

1.  调用成功时："xxx:ok" ，其中xxx为调用的接口名
2.  用户取消时："xxx:cancel"，其中xxx为调用的接口名
3.  调用失败时：其值为具体错误信息