# Node.js 接入 Server酱：脚本/服务出错或任务完成时推送微信（2026 教程）

> 在 Node.js 脚本或服务中集成 Server酱，通过 npm SDK 或原生 fetch API，实现任务完成、程序出错等场景的微信实时通知。

- 网页版：https://sct.ftqq.com/docs/integrations/nodejs/
- 更新日期：2026-07-17

# Node.js + Server酱：脚本/服务状态实时推送微信

> 效果：Node.js 脚本执行完毕、服务出现异常或定时任务完成时，自动发送一条包含详情的消息到你的微信。

## 前置条件

1.  一个 Server酱 SendKey。获取方法：[30 秒获取教程](https://sct.ftqq.com/docs/getting-started/sendkey/)。
2.  一个可运行的 Node.js 环境（建议 Node.js 18 或更高版本）。

## 配置步骤

### 方法一：使用官方 SDK（推荐）

这是最简单的方式，SDK 会自动识别 `SCT` 和 `sctp` 两种 SendKey 格式并调用正确的 API 端点。

1.  **安装 SDK**
    在你的项目目录下，通过 npm 安装 `serverchan-sdk`。
    ```bash
    npm install serverchan-sdk
    ```
2.  **编写推送代码**
    创建一个 `.js` 文件（例如 `notify.js`），写入以下代码。将 `你的SENDKEY` 替换为你的实际 SendKey。
    ```javascript
    // notify.js
    import { scSend } from 'serverchan-sdk'; // 或使用 const { scSend } = require('serverchan-sdk');

    const sendkey = '你的SENDKEY'; // 建议从环境变量 process.env.SERVERCHAN_SENDKEY 读取
    const title = 'Node.js 任务执行报告';
    // 每行之间用空行分隔（Markdown 中单个换行不会分段）
    const desp = [
      '**任务名称**：每日数据备份',
      '**执行状态**：【成功】',
      `**完成时间**：${new Date().toLocaleString()}`,
      '**详情**：已成功备份数据库至云端。',
    ].join('\n\n');

    async function sendNotification() {
      try {
        const response = await scSend(sendkey, title, desp, { tags: '服务器报警' });
        if (response.code === 0) {
          console.log('Server酱 消息推送成功！');
        } else {
          console.error('推送失败：', response);
        }
      } catch (error) {
        console.error('请求出错：', error);
      }
    }

    // 调用函数发送通知
    sendNotification();
    ```
3.  **运行脚本**
    在终端执行你的脚本。
    ```bash
    node notify.js
    ```

### 方法二：使用 Node.js 原生 fetch（无依赖）

如果你不想引入额外依赖，Node.js 18+ 内置的 `fetch` API 可以直接调用 Server酱。

1.  **编写推送代码**
    创建一个 `.js` 文件，写入以下代码。
    ```javascript
    // notify_fetch.js
    const sendkey = '你的SENDKEY'; // 建议从环境变量 process.env.SERVERCHAN_SENDKEY 读取
    const apiUrl = `https://sctapi.ftqq.com/${sendkey}.send`;

    const title = '服务异常告警';
    const desp = [
      '**服务**：用户API服务',
      `**时间**：${new Date().toLocaleString()}`,
      '**错误**：数据库连接超时，请立即检查。',
    ].join('\n\n');

    async function sendNotification() {
      try {
        const response = await fetch(apiUrl, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ title, desp }),
        });
        const result = await response.json();
        if (result.code === 0) {
          console.log('Server酱 消息推送成功！');
        } else {
          console.error('推送失败：', result);
        }
      } catch (error) {
        console.error('网络请求失败：', error);
      }
    }

    // 调用函数发送通知
    sendNotification();
    ```
    *注意：如果你的 SendKey 是 `sctp` 开头，需要根据规则手动构造 API 端点 `https://{uid}.push.ft07.com/send/{sendkey}.send`。SDK 会自动处理这一点。*
2.  **运行脚本**
    ```bash
    node notify_fetch.js
    ```

## 完整示例

以下是一个在定时任务（使用 `node-cron`）完成后推送的完整示例。

1.  **安装依赖**
    ```bash
    npm install serverchan-sdk node-cron
    ```
2.  **创建任务脚本** (`scheduled_task.js`)
    ```javascript
    // package.json 需含 "type": "module"（或改用 require 写法）
    import cron from 'node-cron';
    import { scSend } from 'serverchan-sdk';
    import { someLongRunningTask } from './your-task-module.js'; // 假设这是你的业务函数

    const SENDKEY = process.env.SERVERCHAN_SENDKEY; // 从环境变量读取

    // 定义每天凌晨 2 点执行的任务
    cron.schedule('0 2 * * *', async () => {
      console.log('开始执行每日数据清理任务...');
      try {
        const result = await someLongRunningTask();
        // 任务成功，发送通知
        await scSend(SENDKEY, '定时任务完成', `数据清理任务已成功执行。\n\n处理记录数：${result.count}`);
        console.log('任务完成通知已发送。');
      } catch (error) {
        // 任务失败，发送告警
        await scSend(SENDKEY, '定时任务执行失败', `任务执行过程中发生错误：\n\n\`\`\`\n${error.message}\n\`\`\``);
        console.error('任务失败，告警已发送。', error);
      }
    });

    console.log('定时任务调度器已启动...');
    ```
3.  **设置环境变量并运行**
    ```bash
    export SERVERCHAN_SENDKEY=你的SENDKEY
    node scheduled_task.js
    ```

## 常见问题

**每天可以发多少条消息？**
免费用户每天可发送 5 条。订阅会员目前特价最低 3 元/月，一天最多可发 1000 条（[价格详情](https://sct.ftqq.com/subscribe)）。所有用户每分钟最多发送 50 条。

**消息没收到怎么办？**
请首先访问 [常见问题与排查指南](https://sct.ftqq.com/docs/getting-started/faq/)，按照步骤检查 SendKey、网络及消息内容格式。

**代码中如何安全地存储 SendKey？**
强烈建议使用环境变量，避免将密钥硬编码在代码中。例如：
```bash
# 在命令行中设置（临时）
export SERVERCHAN_SENDKEY=你的SENDKEY
# 在代码中读取
const sendkey = process.env.SERVERCHAN_SENDKEY;
```

**SDK 和直接调用 API 哪个更好？**
SDK 更简单，自动处理了 API 端点识别和请求构造。直接调用 `fetch` 更轻量，无额外依赖。根据项目需求选择即可。

**可以推送到企业微信或钉钉吗？**
可以。Server酱 支持将消息转发到微信服务号、企业微信应用、钉钉群机器人和飞书群机器人。配置方法详见 [通道配置指南](https://sct.ftqq.com/docs/getting-started/channels/)。

## 相关集成

-   [Python 脚本推送](https://sct.ftqq.com/docs/integrations/python/) - 在 Python 脚本中发送通知。
-   [Uptime Kuma 宕机告警](https://sct.ftqq.com/docs/integrations/uptime-kuma/) - 网站监控状态推送。
-   [青龙面板任务通知](https://sct.ftqq.com/docs/integrations/qinglong/) - 定时任务执行结果推送。

<!-- 建议补充关键词：nodejs serverchan, javascript 推送通知, node.js 告警 -->


## 懒人方案：把这段话复制给你的 AI 助手

把下面这段文字原样粘贴给 Claude Code、Cursor 或任何 AI 编程助手，它就会替你完成 Server酱 的接入：

```text
请帮我把 Server酱 微信通知接入到我当前的项目/工具中：
1. API：POST https://sctapi.ftqq.com/{SendKey}.send，参数 title（必填，不能含换行）、desp（正文，支持 Markdown，可选）；成功时返回 JSON 的 code 为 0。
2. 如果我的 SendKey 以 sctp 开头，则改用 https://{uid}.push.ft07.com/send/{SendKey}.send，uid 是 SendKey 中 sctp 与 t 之间的数字。
3. SendKey 从环境变量 SERVERCHAN_SENDKEY 读取；如果没有，提醒我到 https://sct.ftqq.com 免费获取（每天 5 条额度）。
4. 安全要求：不要把 SendKey 硬编码进代码、不要打印到日志、不要提交到 git。
5. 频率约定：任务结束发 1 条结果摘要即可，批量任务合并成一条，不要每步都推。
请根据我当前的项目和场景直接写好代码/配置并验证。
```