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

预定出版插件 有效载荷CMS 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 触发端点 .

安装

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

同伴依赖性 : payload ^3.0.0

快速启动

步骤1——注册插件

// 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 在您的项目根部 :

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

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

外部括号/卷曲

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

节点.js (节点- cron)

import cron from "node-cron";

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

配置参考

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;
}

选项

运行终点

GET /api/scheduled-publish/run

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

认证 : Authorization: Bearer <secret>

成功响应 :

{ "ok": true }

错误响应 :

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

环境变量

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

// 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(中文(简体) )

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

参考文献