# @focus-reactive/payload-plugin-scheduling 中文文档

规范地址：https://npmcn.com/package/%40focus-reactive/payload-plugin-scheduling/

版本：1\.3\.0
npm 元数据更新时间：2026-10-27T09:21:15.210Z
中文译文更新时间：2026-11-15T04:09:49.619Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40focus-reactive/payload-plugin-scheduling
原文对照：https://npmcn.com/package/%40focus-reactive/payload-plugin-scheduling/?lang=original
项目主页：https://github.com/focusreactive/payload-plugins#readme
源码仓库：https://github.com/focusreactive/payload-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：24.2 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：payload ^3\.0\.0
- 首次发布：2026-03-18T10:19:54.254Z
- 最新版本发布：2026-06-18T23:20:50.738Z
- 近 30 天下载量：2613（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

有效载荷 CMS 计划发布插件

## 安装

```sh
npm install @focus-reactive/payload-plugin-scheduling
```

也可以使用：`pnpm add @focus-reactive/payload-plugin-scheduling`、`yarn add @focus-reactive/payload-plugin-scheduling`、`bun add @focus-reactive/payload-plugin-scheduling`

## README

# @ 聚焦- reactive/ payload- plugin- 排程- 发布

预定出版插件 [有效载荷CMS](https://payloadcms.com/) v3. 在任何文件草稿上设定一个未来的发布日期并自动启动——不需要手工发布.

插件启用有效载荷内置 `schedulePublish` 草稿在选定的收藏和全局上,通过一个孤立的队列来引导由此产生的任务,并暴露出一个Bearer-token保护的端点,即您将任务按住以排出队列.

* * *

## AI 整合提示

> 复制并粘贴此提示到您的 AI 助手( Cursor, Claude等) 中, 将插件整合到一个已有的 Biveload 项目中 .

```
I want to add scheduled publication to my Payload CMS v3 project using @focus-reactive/payload-plugin-schedule-publication.

## How it works

The plugin:
1. Enables `drafts.schedulePublish: true` on every collection/global you configure — this makes Payload
   show a "Schedule Publish" date-time picker in the admin sidebar.
2. Routes all `schedulePublish` jobs to an isolated queue (default: "scheduled-publish") so they don't
   interfere with other background jobs.
3. Registers a GET /api/scheduled-publish/run endpoint that, when hit by a cron, calls
   payload.jobs.run({ queue }) to process all due scheduled-publish jobs.
4. The endpoint requires an Authorization: Bearer <secret> header to prevent unauthorized triggers.

## Installation

pnpm add @focus-reactive/payload-plugin-schedule-publication

## Step 1 — Register the plugin in payload.config.ts

import { schedulePublicationPlugin } from '@focus-reactive/payload-plugin-schedule-publication'

// Inside buildConfig({ plugins: [...] })
schedulePublicationPlugin({
  collections: ['pages', 'posts'],  // slugs of collections to enable scheduled publishing on
  globals: ['site-settings'],       // slugs of globals to enable scheduled publishing on (optional)
  secret: process.env.CRON_SECRET!, // any env var you choose — must match the Bearer token your cron sends
})

## Step 2 — Set up a cron to trigger the endpoint

The endpoint GET /api/scheduled-publish/run must be called at least as often as your finest
scheduling granularity (e.g. every minute for minute-level precision).

Pass the secret as a Bearer token:
  Authorization: Bearer <your-secret>

### Vercel (vercel.json)

{
  "crons": [
    {
      "path": "/api/scheduled-publish/run",
      "schedule": "* * * * *"
    }
  ]
}

Note: Set CRON_SECRET in your Vercel project environment variables. Vercel automatically sends
this value in the Authorization header when triggering your cron. Pass it directly to the
plugin's secret option: secret: process.env.CRON_SECRET!

### Any HTTP client / external cron service

curl -X GET https://your-cms.com/api/scheduled-publish/run \
  -H "Authorization: Bearer YOUR_SECRET"

## Important notes

- collections and globals receive `versions.drafts.schedulePublish: true` automatically.
  If a collection already has a versions/drafts config it is preserved and merged.
- The queue option (default: "scheduled-publish") isolates schedule jobs. Change it only if
  you have a naming conflict with other queues.
- Never expose the secret in client-side code. Store it in an environment variable.
```

* * *

## 如何运作

```
Editor sets "Schedule Publish" date in Payload Admin
              ↓
Payload creates a schedulePublish job in the jobs collection
              ↓
         [ queue: "scheduled-publish" ]
              ↓
Cron calls GET /api/scheduled-publish/run  (every minute)
              ↓
Plugin endpoint: payload.jobs.run({ queue: "scheduled-publish" })
              ↓
Due jobs are processed → documents are published
```

插件钩入到有效载荷中 `schedulePublish` 任务 —— 它不执行自己的发布逻辑 。 它只允许您所选择的收藏/ 全球的特性, 将任务引导到指定队列, 并提供 HTTP 触发端点 .

* * *

## 安装

```bash
pnpm add @focus-reactive/payload-plugin-schedule-publication
```

**同伴依赖性 :** `payload ^3.0.0`

* * *

## 快速启动

### 步骤1——注册插件

```ts
// payload.config.ts
import { buildConfig } from "payload";
import { schedulePublicationPlugin } from "@focus-reactive/payload-plugin-schedule-publication";

export default buildConfig({
  plugins: [
    schedulePublicationPlugin({
      collections: ["pages"],
      secret: process.env.CRON_SECRET!,
    }),
  ],
});
```

该插件注入到每个配置的收藏和全局 :

-   `versions.drafts.schedulePublish: true` ——启用管理员侧边栏中的"附表发布"取日期器
-   全体 `schedulePublish` 选项 `"scheduled-publish"` 通过 a 队列 `beforeChange` 任务收藏的钩子

### 步骤2——设置克龙

终点 `GET /api/scheduled-publish/run` 必须定期调用(至少与你最好的排程颗粒性一样频繁)。 它处理队列中的所有应完成的任务并返回 `{ ok: true }`。 。 。 .

#### 维塞尔

添加括号到 `vercel.json` 在您的项目根部 :

```json
{
  "crons": [
    {
      "path": "/api/scheduled-publish/run",
      "schedule": "* * * * *"
    }
  ]
}
```

Vercel 自动发送 `CRON_SECRET` 作为 `Authorization: Bearer $CRON_SECRET` 当触发克伦斯。 设定 `CRON_SECRET` 在您的 Vercel 工程设置中直接传递到插件 `secret` 选项.

#### 外部括号/卷曲

```bash
curl -X GET https://your-cms.com/api/scheduled-publish/run \
  -H "Authorization: Bearer YOUR_SECRET"
```

#### 节点.js (节点- cron)

```ts
import cron from "node-cron";

cron.schedule("* * * * *", async () => {
  await fetch("http://localhost:3000/api/scheduled-publish/run", {
    headers: {
      Authorization: `Bearer ${process.env.CRON_SECRET}`,
    },
  });
});
```

* * *

## 配置参考

```ts
interface SchedulePublicationPluginConfig {
  /**
   * Collection slugs to enable scheduled publishing for.
   * @example ['pages', 'posts']
   */
  collections?: string[];

  /**
   * Global slugs to enable scheduled publishing for.
   * @example ['site-settings']
   */
  globals?: string[];

  /**
   * Queue name to isolate schedulePublish jobs.
   * When set, jobs are routed to this queue and the /scheduled-publish/run
   * endpoint will only process this queue.
   * @default "scheduled-publish"
   */
  queue?: string;

  /**
   * Bearer token used to authenticate calls to the
   * GET /api/scheduled-publish/run endpoint.
   */
  secret: string;
}
```

### 选项

| 选项 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `collections` | `string[]` | 没有 | `[]` | 用于预定出版的收藏 satters |
| `globals` | `string[]` | 没有 | `[]` | 允许预定出版的全局弹簧 |
| `queue` | `string` | 没有 | `"scheduled-publish"` | 隔离已排定的出版任务的队列名称 |
| `secret` | `string` | **对** | —— 说 | 调用运行端点所需的接线符 |

* * *

## 运行终点

`GET /api/scheduled-publish/run`

触发已排定的排队中所有到期任务的处理 .

**认证 :** `Authorization: Bearer <secret>`

**成功响应 :**

```json
{ "ok": true }
```

**错误响应 :**

```json
{ "error": "Unauthorized" }   // 401 — missing or wrong token
{ "error": "Internal server error" }  // 500 — jobs runner threw
```

* * *

## 环境变量

该插件的 `secret` 选项接受任何环境变量——使用适合您的平台的名称。 在Vercel,自然的选择是 `CRON_SECRET`自动发送 `Authorization: Bearer` 触发克龙时的头部.

```ts
// On Vercel
secret: process.env.CRON_SECRET!

// On any other platform
secret: process.env.MY_CRON_SECRET!
```

* * *

## 版本起草行为( D)

插件调用 `injectSchedulePublishToVersions` 每个配置的收藏/全局配置 :

-   如果收藏没有 `versions` 配置 + 添加 `{ drafts: { schedulePublish: true } }`
-   若为 `versions` 实值 `true` 或已经 `drafts: true` 替换 `drafts` 与 `{ schedulePublish: true }`
-   若为 `versions.drafts` 是对象 − 合并 `schedulePublish: true` 保留其他备选案文草案(例如:. `autosave`(中文(简体) )

您的现有版本/ 草稿配置从未被丢弃 .

* * *

## 参考文献

| 导入路径 | 出口 |
| --- | --- |
| `@focus-reactive/payload-plugin-schedule-publication` | `schedulePublicationPlugin`, (中文(简体) ), `SchedulePublicationPluginConfig` |

## 常见问题

### @focus-reactive/payload-plugin-scheduling 是什么？

有效载荷 CMS 计划发布插件

### 如何安装 @focus-reactive/payload-plugin-scheduling？

在项目目录运行 npm install @focus-reactive/payload-plugin-scheduling，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：payload（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @focus-reactive/payload-plugin-scheduling 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @focus-reactive/payload-plugin-scheduling 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @focus-reactive/payload-plugin-scheduling 可以商用吗？

@focus-reactive/payload-plugin-scheduling 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @focus-reactive/payload-plugin-scheduling 的下载量有多少？

根据 npm 官方下载统计，@focus-reactive/payload-plugin-scheduling 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,613 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @focus-reactive/payload-plugin-scheduling 还在维护吗？

最新版本 1\.3\.0 发布于 2026/06/19（4 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/03/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。