# @cmssy/next 中文文档

规范地址：https://npmcn.com/package/%40cmssy/next/

版本：19\.30\.0
npm 元数据更新时间：2026-11-06T09:04:45.674Z
中文译文更新时间：2026-11-10T04:24:07.518Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：67.8 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：next \>=15，react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0，@cmssy/react ^19\.30\.0
- 首次发布：2026-06-06T20:28:51.115Z
- 最新版本发布：2026-11-06T09:04:45.296Z
- 近 30 天下载量：6166（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：222（近 12 个月 222 个）

## 中文简介

Next.js App 无头站点的路由器绑定(创建 CmsyPage + 草稿预览)

## 安装

```sh
npm install @cmssy/next
```

也可以使用：`pnpm add @cmssy/next`、`yarn add @cmssy/next`、`bun add @cmssy/next`

## README

# @ cmssy/ next

Next.js (App 路由器) 绑定 a [学问](https://cmssy.com/) 无头站. 一条通通的路由会让您发布 cmsy 内容与本地块 组件,在其中构建活版编辑-模式预览。 与 [`@cmssy/react`](https://www.npmjs.com/package/@cmssy/react) (块+数据).

```bash
pnpm add @cmssy/next @cmssy/react
```

## 翻出每一页

```tsx
// app/[[...path]]/page.tsx
import { createCmssyPage } from "@cmssy/next/server";
import { cmssy } from "@/cmssy/config";
import { blocks } from "@/cmssy/blocks";
import { CmssyEditor } from "@/cmssy/editor";

export default createCmssyPage(cmssy, blocks, { editor: CmssyEditor });
```

```ts
// cmssy/config.ts
import { defineCmssyConfig } from "@cmssy/next";

// defineCmssyConfig validates the required env vars and throws a clear error if
// any is missing - never mask them with `?? ""` (an empty org/slug builds a
// broken delivery URL like `/public//graphql`).
export const cmssy = defineCmssyConfig({
  org: process.env.CMSSY_ORG_SLUG,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,
  draftSecret: process.env.CMSSY_DRAFT_SECRET, // edit-mode preview handshake
  // apiUrl + editorOrigin default to cmssy cloud; set them only for self-host/staging.
  // Locales come from the workspace site config - no need to repeat them here.
});
```

`createCmssyPage` 获取请求路径的已发布的页面并制作 它; 未出版的一页回答 404. 它不处理编辑器 - 这需要 下面的编辑路径和代理。 一个出版的建筑确实 **没有** 需求 `editorOrigin`。 。 。 .

## 让编辑器设定您的网站

Cmsy 编辑器以 `?cmssyEdit=1&cmssySecret=<draft secret>`代理验证该秘密 将请求重写到 `/cmssy-edit/...`,使草案内容与  `editor`。需要两个文件;没有这两个文件,编辑会报告: 预览没有响应.

```tsx
// app/cmssy-edit/[[...path]]/page.tsx
import { createCmssyEditPage } from "@cmssy/next/server";
import { cmssy } from "@/cmssy/config";
import { blocks } from "@/cmssy/blocks";
import { CmssyEditor } from "@/cmssy/editor";

export const dynamic = "force-dynamic";

export default createCmssyEditPage(cmssy, blocks, { editor: CmssyEditor });
```

```ts
// proxy.ts (Next.js 16) - on Next.js 15 name it middleware.ts and export `middleware`
import { createCmssyProxy } from "@cmssy/next/middleware";
import { cmssy } from "@/cmssy/config";

export const proxy = createCmssyProxy(cmssy);
export const config = { matcher: ["/((?!_next/|api/|.*\\..*).*)"] };
```

`proxy.ts` 坐在旁边 `app/` (单位:千美元) `src/` 当应用程序是 `src/app`) (中文(简体) ). 设定 工作空间预览 URL 到精确的部署来源, 例如 . `https://my-site.vercel.app`。 。 。 .

## 预览草稿

```ts
// app/api/draft/route.ts
import { createDraftRoute } from "@cmssy/next/server";
export const GET = createDraftRoute(cmssy);
```

## 缓存,并在发布时过期

```ts
// app/[[...path]]/page.tsx
export const revalidate = 3600;
const cache = { revalidate };
export default createCmssyPage(cmssy, blocks, { editor: CmssyEditor, cache });

// app/api/revalidate/route.ts
import { createCmssyRevalidateRoute } from "@cmssy/next/server";
export const POST = createCmssyRevalidateRoute({
  secret: process.env.CMSSY_WEBHOOK_SECRET,
});
```

`cache` 将 SDK 发布的读取到下一个数据缓存 `cmssy-content` 标签; 已验证的路由过期 `content.changed` (原始内容存档于2017-10-21). webhook. 草稿模式和编辑器总是在现场阅读.

## 编辑模式 CSP

`createCmssyProxy` 已经设置在编辑器请求中 。 对于一个手写代理, `applyCmssyCsp(response, { editorOrigin: cmssy.editorOrigin })` 从 `@cmssy/next/middleware` 让 cmsy 编辑器设定响应.

## 本地化导航(路径前缀)

活动地块生活在 URL 路径前缀中(`/en/about`; 默认区域 保持裸体). `createCmssyPage` 解决它,并揭露它通过 `CmssyLocaleProvider`。 。 。 . 内部链接必须带有前缀 前缀为您自己 `localizeHref` 将结果传递给 `next/link`数字 :

```tsx
// any block component
import Link from "next/link";
import { localizeHref } from "@cmssy/next";

<Link href={localizeHref("/about", locale)}>About</Link>; // → /en/about while EN is active
```

根版式无法读取路径, 因此代理从 : 路径前缀: `createCmssyProxy` 从编辑部分已经做了.

`localizeHref(href, locale)` 编辑 `CMSSY_LOCALE_HEADER` 常数为 从 `@cmssy/next` (和 `@cmssy/core`) (中文(简体) ).

## 出口

`@cmssy/next/server`数字 : `createCmssyPage`, (中文(简体) ), `createCmssyEditPage`, (中文(简体) ), `createDraftRoute`, (中文(简体) ), `createCmssyRevalidateRoute`, (中文(简体) ), `createCmssyBlockDataRoute`, (中文(简体) ), `CmssyLayoutSlot`, (中文(简体) ), `resolveCmssyLayout`, (中文(简体) ), `isCmssyEditMode`。 。 。 . `@cmssy/next/middleware`数字 : `createCmssyProxy`, (中文(简体) ), `cmssyEditRewrite`, (中文(简体) ), `applyCmssyCsp`, (中文(简体) ), `isCmssyEditRequest`。 。 。 . 根 : `defineCmssyConfig`, (中文(简体) ), `localizeHref`, (中文(简体) ), `nextRetryMode`, (中文(简体) ), `cmssyCachedFetch`, (中文(简体) ), `CMSSY_CONTENT_TAG` 和类型。 完整名单,有签名,在 [文献/参考资料/sdk-api.md](https://npmcn.com/package/docs/reference/sdk-api.md)。 。 。 .

## 版本: 此软件包, 不是 API

**固定此套件不会将它所讲的API 绑起 .** 软件包版本 包括这个客户 - 其出口及其行为,正常的铸币. 阴道 aPI是一个主机服务,其GraphQL计划可以在任何部署上改变, 在这儿没有释放权.

API 版本没有日期标注; 发送端没有版本 部分。 今天保护你的是 断裂的策略改变不能合并 沉默地 - 它被一个能验证SDK自身操作的门抓住 无论如何,运输一个需要记录 批准 - 而我们打算 删除已标记 `@deprecated` 先说 没有保证的折旧窗口 并且没有最低的通知期。 详细情况 [`@cmssy/core`](https://www.npmjs.com/package/@cmssy/core)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @cmssy/next 是什么？

Next\.js App 无头站点的路由器绑定\(创建 CmsyPage \+ 草稿预览\)

### 如何安装 @cmssy/next？

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

### @cmssy/next 支持 TypeScript 吗？

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

### @cmssy/next 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cmssy/next 需要什么版本的 Node\.js？

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

### @cmssy/next 可以商用吗？

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

### @cmssy/next 的下载量有多少？

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

### @cmssy/next 还在维护吗？

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