# @delmaredigital/payload-puck 中文文档

规范地址：https://npmcn.com/package/%40delmaredigital/payload-puck/

版本：0\.11\.0
npm 元数据更新时间：2026-11-09T15:26:18.136Z
中文译文更新时间：2026-11-11T21:46:00.200Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40delmaredigital/payload-puck
原文对照：https://npmcn.com/package/%40delmaredigital/payload-puck/?lang=original
项目主页：https://plugins.delmaredigital.com/puck
源码仓库：https://github.com/delmaredigital/payload-puck

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

- 包体积（解压后）：1.9 MB，449 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.9\.0
- 运行依赖：17 个
- peer 依赖：zod \>=3\.0\.0，next \>=15\.4\.8，react \>=19\.2\.1，payload \>=3\.69\.0，react-dom \>=19\.2\.1，tailwindcss \>=3\.0\.0 \|\| \>=4\.0\.0，@payloadcms/ui \>=3\.69\.0，@payloadcms/next \>=3\.69\.0，@puckeditor/core \>=0\.24\.0，@tailwindcss/postcss \>=4\.0\.0
- 首次发布：2026-01-08T19:53:22.777Z
- 最新版本发布：2026-11-09T15:26:17.710Z
- 近 30 天下载量：6789（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

Puck 可视页面构建器插件

## 安装

```sh
npm install @delmaredigital/payload-puck
```

也可以使用：`pnpm add @delmaredigital/payload-puck`、`yarn add @delmaredigital/payload-puck`、`bun add @delmaredigital/payload-puck`

## README

# @ delmaredigital/ payload- puck

用于集成的有效载荷CMS插件 [纸](https://puckeditor.com/) 视觉页面构建器. 在利用有效载荷内容管理能力的同时,以拖放组件构建可视化页面.

[![Starter Template - Use This](https://img.shields.io/badge/Starter_Template-Use_This-blue?style=for-the-badge&logo=github&logoColor=white)](https://github.com/delmaredigital/dd-starter)

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D)

**联合国** [插件. delmaredigital.com/docs/puck 页面存档备份,存于互联网档案馆](https://plugins.delmaredigital.com/docs/puck) • 妇女 [概览](https://plugins.delmaredigital.com/puck)

> ⚠️ **从0.9升级到0.10.x? 中断——需要 `@puckeditor/core` 0.24 (英语).** 运行 `pnpm add @puckeditor/core@^0.24.0`。内置组件现在用 General / Style / 版式标签安排其侧边栏字段,动作栏显示拖动手柄(`dnd={{ enableDragHandle: false }}` 打开 `PuckEditor` 藏来. 已保存的页面数据不变 。 0.10.1 只提高受抚养人的最低生活费. **0.10.2 安全装置——建议升级:** 管理员编辑器视图现在应用了收藏的读取权限。 它还使管理员编辑器全屏,画布不再继承管理员页面的 CSS;列出您在其中需要预览的任何样式表 `editorStylesheets`。 。 。 . **0.10.3 添加: `integrations`** (来自其他软件包的组件、类别和编辑器插件的组合);不使用它们则无所变化. **0.11.0 是一个安全固定和断裂:** 匿名的呼叫者只能读取已出版的页面( 已关闭的草稿的收集不受影响), 因此没有签名的用户读取草稿的预览必须通过一个或一组 `access.read`; 见 [升级](https://plugins.delmaredigital.com/docs/puck/upgrading)见 [变化](https://npmcn.com/package/%40delmaredigital/payload-puck/CHANGELOG.md)。 。 。 .
> 
> 是从旧版本来的? 这个 [升级指南](https://plugins.delmaredigital.com/docs/puck/upgrading) 列出每次破解或安全释放需要的内容.

* * *

## 文档

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/delmaredigital/payload-puck)

覆盖安装,配置,组件,自定义字段,主题,布局,暗模式,页面-树木集成,混合集成,AI集成等.

* * *

## 安装

```bash
pnpm add @delmaredigital/payload-puck @puckeditor/core
```

### 所需资源

| 依赖性 | 版本 |
| --- | --- |
| `node` | \>= 20.9.0 |
| `@puckeditor/core` | 页:1 |
| `payload` | 页:1 |
| `@payloadcms/next` | 页:1 |
| `next` | \* 15.4.8(见下文安全说明) |
| `react` | 页:1 |

> **使用 [`@delmaredigital/payload-better-auth`](https://github.com/delmaredigital/payload-better-auth)? 吗?** 任何出版的版本作品——其认证策略邮票 `collection` ,这是0.9访问解析度所需要的. **建议0.9.0或以后:** 这是第一次发布 建议 `payload.auth()` 接线与请求头 0.9 现在转发到有效载荷 API-key请求没有副作用. 目前为 `0.11.3`,这需要更好的 Auth `1.7`。 。 。 .

> **说明:** Puck 0.21+ 从 `@measured/puck` 改为 `@puckeditor/core`。此插件需要新的软件包范围.

> **警卫:** 如果您的应用程序使用 Next.js 中间软件( 或代理. ts)来保护动态路由, 请使用 `next` >= 15.5.16 / 16.2.5 接接接 [CVE-2026-44574 (英语)](https://github.com/vercel/next.js/security/advisories/GHSA-492v-c6pp-mqqv) (中间软件通过动态路由参数注入绕行). Turbopack用户需要 ++ 15.5.18 / 16.2.6.

* * *

## 快速启动

### 1\. 添加插件

```typescript
// src/payload.config.ts
import { buildConfig } from 'payload'
import { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'

export default buildConfig({
  plugins: [
    createPuckPlugin({
      pagesCollection: 'pages',
    }),
  ],
})
```

### 2\. 提供Puck配置

```typescript
// app/(app)/layout.tsx
import { PuckConfigProvider } from '@delmaredigital/payload-puck/client'
import { editorConfig } from '@delmaredigital/payload-puck/config/editor'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PuckConfigProvider config={editorConfig}>
          {children}
        </PuckConfigProvider>
      </body>
    </html>
  )
}
```

### 3\. 创建前端路径

```typescript
// app/(frontend)/[[...slug]]/page.tsx
import { getPayload } from 'payload'
import config from '@payload-config'
import { PageRenderer } from '@delmaredigital/payload-puck/render'
import { baseConfig } from '@delmaredigital/payload-puck/config'
import { notFound } from 'next/navigation'

async function getPage(slug?: string[]) {
  const payload = await getPayload({ config })
  const slugPath = slug?.join('/') || ''
  const { docs } = await payload.find({
    collection: 'pages',
    where: {
      and: [
        { _status: { equals: 'published' } },
        slugPath
          ? { slug: { equals: slugPath } }
          : { isHomepage: { equals: true } },
      ],
    },
    limit: 1,
  })
  return docs[0] || null
}

export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
  const { slug } = await params
  const page = await getPage(slug)
  if (!page) notFound()
  return <PageRenderer config={baseConfig} data={page.puckData} />
}
```

就这样! 插件自动登记编辑器视图、 API 端点和“ 用 Puck 编辑” 按钮.

复制启动文件从 [GitHub 图像](https://github.com/delmaredigital/payload-puck/tree/main/examples) 或 [启动文件指南](https://plugins.delmaredigital.com/docs/puck/guides/starter-files)。见 [实例/README.md](https://npmcn.com/package/%40delmaredigital/payload-puck/examples/README.md) 用于文件指南和设置注释。 仅限Npm包船 `dist`;示例必须从 GitHub 或文件复制。 贡献者可以对照源出口进行核查 `pnpm typecheck:examples`。 。 。 .

* * *

## 文档

关于其他一切——组件,自定义字段,主题,布局,暗模式,页面-树木集成,混合集成,AI集成,高级配置,以及完整的导出参考——参见: [完整文档](https://plugins.delmaredigital.com/docs/puck)。 。 。 .

* * *

## 一体化

一个集成捆绑了Puck组件,类别和可选编辑器插件. 主机组件和类别字段胜出;集成填充缺失的组件密钥和附件类别名. 配置助手忽略插件 .

```tsx
// Render config
import { extendConfig, baseConfig, type PuckIntegration } from '@delmaredigital/payload-puck/config'

const integrations: readonly PuckIntegration[] = [{
  name: 'dummy',
  components: { DummyBlock: { render: () => <div>Dummy block</div> } },
  categories: { custom: { title: 'Custom', components: ['DummyBlock'] } },
}]

export const renderConfig = extendConfig({ base: baseConfig, integrations })
```

```tsx
'use client'

import { PuckConfigProvider, type PuckIntegration } from '@delmaredigital/payload-puck/client'
import { editorConfig } from '@delmaredigital/payload-puck/config/editor'
import type { ReactNode } from 'react'

const integrations: readonly PuckIntegration[] = [{
  name: 'dummy',
  components: { DummyBlock: { render: () => <div>Dummy block</div> } },
  categories: { custom: { title: 'Custom', components: ['DummyBlock'] } },
}]

export function EditorProvider({ children }: { children: ReactNode }) {
  return <PuckConfigProvider config={editorConfig} integrations={integrations}>{children}</PuckConfigProvider>
}
```

一旦在模块范围创建集成数组:每个渲染者新建数组重建编辑器配置. `PuckEditor` 还接受 `integrations` 直接说 集成插件遵循道具和上下文插件;被命名的集成插件被针对道具,上下文和更早的集成插件去dud. `plugins={false}` 在集成组件仍在应用时禁用所有插件.

编辑器应用集成而不 `exclude`,因此选择退出集成组件,从提供者中省略集成,或者在同一键下定义自己的组件,后者获胜.

## 在槽上进行实验

使用 [@ delmaredigital/ paidload- experiments (英语)](https://www.npmjs.com/package/@delmaredigital/payload-experiments) 通过整合在Puck槽上进行实验. 工作:有效载荷试验.

## 许可证

麻省理工学院

## 常见问题

### @delmaredigital/payload-puck 是什么？

Puck 可视页面构建器插件

### 如何安装 @delmaredigital/payload-puck？

在项目目录运行 npm install @delmaredigital/payload-puck，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=15\.4\.8）、react（\>=19\.2\.1）、payload（\>=3\.69\.0）、react-dom（\>=19\.2\.1）、@puckeditor/core（\>=0\.24\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @delmaredigital/payload-puck 支持 TypeScript 吗？

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

### @delmaredigital/payload-puck 支持 ESM 还是 CommonJS？

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

### @delmaredigital/payload-puck 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @delmaredigital/payload-puck 可以商用吗？

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

### @delmaredigital/payload-puck 的下载量有多少？

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

### @delmaredigital/payload-puck 还在维护吗？

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