支付宝小程序插件开发完全指南：从设计到发布全链路实践

偷光

已于 2025-06-29 00:30:47 修改

阅读量1.1k

点赞数 19

CC 4.0 BY-SA版权

文章标签：小程序前端 javascript

于 2025-06-29 00:28:10 首次发布

本文链接：https://blog.youkuaiyun.com/wbskb/article/details/148984548

一、准备工作

1. 注册开发者账号

访问支付宝开放平台
注册并实名认证个人或企业开发者账号。

2. 创建插件项目

登录 支付宝开放平台 → 进入【小程序开发】→【插件管理】。
点击“创建插件”，填写插件基本信息（如名称、简介、类目等）。
审核通过后即可获得插件 ID 和基础配置信息。

二、开发插件

1. 下载并安装 IDE 工具

使用 支付宝开发者工具（IDE）
- 下载地址：支付宝开发者工具下载页面
- 安装完成后登录你的开发者账号。

2. 创建插件工程

打开支付宝开发者工具，选择“新建项目”。
类型选择为“插件项目”，输入插件 ID。
配置 AppID（可选，用于本地调试）。
设置项目路径和模板（可以选择空模板或示例模板）。

在这里插入图片描述

关键文件说明：

`plugin.json` 文件说明

plugin.json：定义插件的接口、页面、权限等，是支付宝小程序插件的配置文件，用于定义插件的行为、导出组件和页面等信息。它决定了插件如何被主程序引用以及插件内部的功能暴露方式。

{
  "publicComponents": {
    "list": "components/list/list"
  },
  "publicPages": {
    "hello-page": "pages/index/index"
  },
  "pages": [
    "pages/index/index"
  ],
  "main": "index",
  "lazyCodeLoading": "renderedComponents",
  "behavior": {
    "requestReferrerStrategy": "page"
  }
}

1. `"publicComponents"`（公开组件）

"publicComponents": {
  "list": "components/list/list"
}

作用：声明插件中对外暴露的可复用组件。
结构说明：
- 键名 "list" 是组件在主程序中使用的名称。
- 值 "components/list/list" 是组件文件路径（不带扩展名）。
使用方式：主程序可以直接通过 <list /> 标签使用该组件。
注意：组件必须是一个完整的自定义组件目录（包含 .axml, .acss, .js, .json 文件）。

2. `"publicPages"`（公开页面）

"publicPages": {
  "hello-page": "pages/index/index"
}

作用：声明插件中可以被主程序跳转或打开的页面。
结构说明：
- 键名 "hello-page" 是页面在主程序中调用时的标识。
- 值 "pages/index/index" 是页面文件路径（不带扩展名）。
使用方式：主程序可以通过 my.navigateTo({ url: 'hello-page' }) 等 API 跳转到插件中的页面。
限制：公开页面不能直接作为主程序的首页。

3. `"pages"`（插件本地页面列表）

"pages": [
  "pages/index/index"
]

作用：定义插件自身的页面路径列表，用于插件内部导航或调试。
注意：这个字段不会影响主程序对插件页面的调用，仅用于插件自身运行时。

4. `"main"`（入口文件）

"main": "index"

作用：指定插件的主入口文件，通常是一个 .js 文件（如 index.js）。
用途：用于导出插件对外暴露的方法或数据，供主程序调用。
示例：index.js 中可以导出一个对象，主程序通过 requirePlugin() 引入并调用其中的方法。

5. `"lazyCodeLoading"`（懒加载策略）

"lazyCodeLoading": "renderedComponents"

作用：控制插件代码的加载策略，优化性能。
可选值：
- "none"：默认加载所有代码。
- "renderedComponents"：只加载当前渲染需要的组件及其依赖。
推荐设置：对于大型插件，建议使用 "renderedComponents" 来减少初始加载体积。

6. `"behavior"`（行为配置）

"behavior": {
  "requestReferrerStrategy": "page"
}

作用：定义插件的一些特殊行为规则。
requestReferrerStrategy 字段说明：
- "page"：请求来源为当前页面。
- "plugin"：请求来源为插件本身。
- "custom"：自定义来源（需配合 referrer 参数）。
用途：主要用于区分网络请求的来源，便于后端进行日志记录或权限控制。

`blank/plugin/index.js` 文件说明

blank/plugin/index.js：导出插件的方法供主程序调用。是支付宝小程序插件的主入口文件，它定义了插件对外暴露的功能和接口。通过这个文件，插件可以将内部的方法、数据或服务提供给主程序调用。

var data = require('./api/data')

module.exports = {
  getData: data.getData,
  setData: data.setData
}

部分	描述
`require('./api/data')`	引入插件内部的 `data.js` 模块
`module.exports`	将 `data.js` 中的方法导出，供主程序调用
`getData` / `setData`	插件对外暴露的两个方法，分别用于获取和设置数据

三、主程序中使用插件

1. 引入插件

app.json：适用于全局引入插件，所有页面都可以使用。
页面 .json 文件：仅在当前页面中使用插件，节省资源。

在主小程序的 app.json 或页面 .json 文件中添加插件引用：

{
  "plugins": {
    "myPlugin": {
      "version": "1.0.0",
      "provider": "插件AppID"
    }
  }
}

字段	类型	必填	描述
`plugins`	Object	是	插件引用对象，用于声明使用的插件
`myPlugin`	String	是	插件的本地引用名（可以自定义，如 `myPlugin`, `utils`, `sharePlugin` 等）
`version`	String	是	插件版本号，必须与插件发布时的版本一致
`provider`	String	是	插件 AppID，即插件开发者的唯一标识，在插件详情页可查到

2. 调用插件方法

在页面 JS 中引入插件并调用其方法：

const myPlugin = requirePlugin("myPlugin");

Page({
  onLoad() {
    const result = myPlugin.sayHello("Qwen");
    console.log(result); // 输出: Hello, Qwen
  }
});

使用 `requirePlugin()` 方法引入插件对象

const myPlugin = requirePlugin("myPlugin");

注意：这里的 "myPlugin" 要和你在 .json 文件中定义的插件名称一致。

调用插件方法（假设插件暴露了 `getData` 和 `setData`）

Page({
  onLoad() {
    // 调用插件的方法
    const data = myPlugin.getData();
    console.log(data);

    myPlugin.setData("新的数据");
  }
});

使用插件中的组件或页面

如果插件中通过 plugin.json 暴露了组件或页面，也可以直接使用它们：

使用插件组件：

<list />

前提：插件的 plugin.json 中有类似 "publicComponents": { "list": "components/list/list" }

跳转到插件页面：

my.navigateTo({
  url: 'hello-page'
});

前提：插件的 plugin.json 中有类似 "publicPages": { "hello-page": "pages/index/index" }

四、测试与调试

1. 本地调试

在开发者工具中运行插件项目。
可以通过模拟器或真机调试插件功能。

2. 主程序联调

将插件上传为“开发版本”。
主程序在 IDE 中设置为“插件开发调试模式”，可以实时加载插件代码进行调试。

要先在支付宝开发平台创建一个小程序插件应用，并将本地文件将其关联，才能生成预览码，生成预览码后复制其dev 版本号，在宿主小程序里边使用就可以了。

注意：要在插件小程序里边的白名单内的小程序才可以使用插件

点击预览后生成类似dev_1234567890格式的dev版本号。

在这里插入图片描述

修改宿主小程序的 app.json 或页面 .json

{
  "plugins": {
    "myPlugin": {
      "version": "dev_1234567890",
      "provider": "你的插件AppID"
    }
  }
}

域名白名单必须配置

插件中所有网络请求都必须配置域名白名单。
白名单在开放平台插件详情页 → 【开发管理】→【域名管理】中配置。

五、发布插件

1. 提交审核

插件开发完成后，在开放平台提交插件版本。
填写更新日志、截图等信息。
提交后等待支付宝平台审核（通常1~3个工作日）。

2. 发布插件

审核通过后，可在插件详情页点击“上线”。
上线后其他开发者即可在自己的小程序中引用该插件。

六、插件更新与维护

每次修改插件代码后，需重新上传新版本。
更新版本号（如从 1.0.0 到 1.0.1）。
更新后通知主程序开发者同步插件版本。

七、注意事项

事项	说明
权限控制	插件访问某些 API 需要申请权限，并在 `plugin.json` 中声明
插件大小限制	插件包体积不能超过 2MB
插件版本	每个版本必须有唯一版本号，建议遵循语义化版本规范（如 1.0.0）
接口安全	插件中的网络请求需要域名白名单配置

八、文档与资源

官方文档：支付宝小程序插件开发文档
示例插件：可在 GitHub 或支付宝开放平台上查找官方示例插件
社区支持：支付宝开发者论坛

如果你是在团队协作中开发插件，建议建立以下文档规范：

文档	内容
`README.md`	插件功能介绍、使用方式、依赖说明
`CHANGELOG.md`	插件版本变更记录
`USAGE.md`	插件调用示例和常见问题
`LICENSE`	插件授权协议（如 MIT）