接入方式

Unicall 的目标是同时服务 npm 包接入和浏览器构建产物接入。Node.js 服务端是推荐运行环境；浏览器只适合公开目标或后端代理场景。

包管理器安装

pnpm

pnpm add @noblesnowfield/unicall

npm

npm install @noblesnowfield/unicall

yarn

yarn add @noblesnowfield/unicall

Node.js ESM

import { createDefaultProviderRegistry, notify } from '@noblesnowfield/unicall';

await notify(
  'pushplus://PUSHPLUS_TOKEN?template=markdown',
  {
    title: '构建完成',
    markdown: '## CI\n\n构建已经通过。'
  },
  {
    registry: createDefaultProviderRegistry()
  }
);

直接下载构建产物

SDK 构建后会输出 dist。如果你不通过包管理器安装，可以下载发布包里的构建产物，再按运行环境引用：

dist/index.js          Node / Bundler ESM
dist/index.cjs         CommonJS
dist/browser/index.js  Browser ESM
dist/browser/index.iife.js  Browser <script>

浏览器 ESM

<script type="module">
  import { notify } from './dist/browser/index.js';

  await notify('webhook://api.example.com/public-notice', {
    title: '浏览器通知',
    text: '只发送到无敏感凭据的公开接口。'
  });
</script>

浏览器入口导出 Runtime、ProviderRegistry、中间件、解析器和错误类型，不默认导出需要服务端密钥的首批 Provider。

浏览器 <script>

<script src="./dist/browser/index.iife.js"></script>
<script>
  const { notify } = window.Unicall;

  notify('webhook://api.example.com/public-notice', {
    title: '浏览器通知',
    text: '这类调用应经过你自己的后端代理。'
  });
</script>

如果你的构建产物使用了不同的全局变量名，请以实际发布包为准。

浏览器安全限制

不要在前端暴露这些敏感值：

• 企业微信、飞书、钉钉等企业协作机器人的签名密钥。
• SMTP 账号、授权码、密码。
• Pushplus token、WxPusher appToken、喵提醒喵码。
• 任何能直接代表服务端身份发送通知的凭据。

推荐方案是让浏览器请求你自己的后端接口，后端使用 unicall 读取 Secret 并发送通知。

Browser -> 你的后端 /api/notify -> Unicall Runtime -> Provider

JS 配置文件接入

测试和生产都推荐用 JS/TS 配置管理渠道结构、profile、模板和默认值，环境变量只承载真实敏感值。

export default {
  defaultProfile: process.env.UNICALL_PROFILE ?? 'default',
  channels: {
    pushplus: {
      default: {
        token: process.env.UNICALL_PUSHPLUS_DEFAULT_TOKEN,
        template: 'markdown'
      }
    }
  }
};

本地开发时建议使用这两个文件：

unicall.config.local.mjs  管理 channels、profiles、templates
.env.local                只存放真实 token、授权码、收件人等值

unicall.config.local.mjs 不应该直接写死敏感值，而是引用 process.env：

export default {
  defaultProfile: process.env.UNICALL_PROFILE ?? 'default',
  channels: {
    email: {
      default: {
        service: process.env.UNICALL_EMAIL_DEFAULT_SERVICE || 'qq',
        user: process.env.UNICALL_EMAIL_DEFAULT_USER,
        pass: process.env.UNICALL_EMAIL_DEFAULT_PASS,
        from: process.env.UNICALL_EMAIL_DEFAULT_FROM,
        fromName: process.env.UNICALL_EMAIL_DEFAULT_FROM_NAME ?? '通知应用',
        to: process.env.UNICALL_EMAIL_DEFAULT_TO?.split(',') ?? []
      }
    }
  },
  templates: {
    email: {
      default: {
        messageType: 'html',
        template: 'gameNotification',
        templateOptions: {
          appName: '通知应用',
          eventName: '服务提醒',
          eventTitle: '每日巡检完成',
          eventDescription: '所有核心接口均通过健康检查。'
        }
      }
    }
  }
};

真实环境变量使用统一命名：

UNICALL_<CHANNEL>_<PROFILE>_<FIELD>

例如：

UNICALL_PUSHPLUS_DEFAULT_TOKEN=
UNICALL_EMAIL_DEFAULT_PASS=
UNICALL_WXPUSHER_DEFAULT_APP_TOKEN=

本地 env 配置流程

从零开始配置本地提醒时，推荐按这个顺序：

1. 复制 .env.example 为 .env.local。
2. 复制 unicall.config.example.mjs 为 unicall.config.local.mjs。
3. 在 .env.local 填真实值，例如 UNICALL_PUSHPLUS_DEFAULT_TOKEN 或 UNICALL_EMAIL_DEFAULT_PASS。
4. 在 unicall.config.local.mjs 里选择 profile 和模板，例如 templates.email.default。
5. 使用手动脚本或本地测试页发送提醒。

手动脚本示例：

pnpm exec tsx scripts/send/email.ts --profile default
pnpm exec tsx scripts/send/pushplus.ts --profile default
pnpm exec tsx scripts/send/wxpusher.ts --profile default

本地测试页示例：

pnpm build
pnpm run push:ui

然后打开：

http://127.0.0.1:4317

WxPusher 需要绑定用户 UID 时，本地测试页提供两条路径：不搭服务器时点击 开始扫码绑定，页面自动创建参数二维码并轮询回填 UID；搭服务器时配置公网回调地址，测试页收到回调后也会自动回填 UID。

如果你要发送 HTML 模板，先确认渠道支持 HTML，再查看 HTML 模板。