# @contentrail/core 中文文档

规范地址：https://npmcn.com/package/%40contentrail/core/

版本：0\.2\.6
npm 元数据更新时间：2026-11-08T11:01:31.383Z
中文译文更新时间：2026-11-11T01:20:44.062Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40contentrail/core
原文对照：https://npmcn.com/package/%40contentrail/core/?lang=original
项目主页：https://github.com/Hridhin-k/contentrail#readme
源码仓库：https://github.com/Hridhin-k/contentrail

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

- 包体积（解压后）：43.7 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：zod ^4\.6\.7
- 首次发布：2026-10-29T21:10:35.843Z
- 最新版本发布：2026-11-08T11:01:31.165Z
- 近 30 天下载量：2304（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

框架独立的ContentRail计划,验证,和内容类型.

## 安装

```sh
npm install @contentrail/core
```

也可以使用：`pnpm add @contentrail/core`、`yarn add @contentrail/core`、`bun add @contentrail/core`

## README

# `@contentrail/core`

框架独立的ContentRail schemas,校验,并推断出内容类型.

此软件包定义 **仅收集并验证**。它不读取文件、与网络交谈、存储内容、认证用户或发布网站.

## 所需资源

-   节点.js **第22条** (单位:千美元)`engines.node`(中文(简体) )
-   为消费者推荐的脚本类型 5.9+
-   [佐德语Name](https://zod.dev/) `^4.6.7` (依赖性+对等点;本地) `zod` 条目-不 `zod/v3`(中文(简体) )

偏爱 `validateEntry` 编号 : `validateCollection` 编号 : `assertValidEntry` 对不可信者 输入。 通话 `schema.safeParse()` 直接绕过ContentRail JSON边界.

从内容文件夹升级 `0.1.0` (第3区):见 `docs/MIGRATION_ZOD4.md`。 。 。 .

## 安装

### Monorepo( 当前)

```sh
pnpm install
pnpm --filter @contentrail/core build
```

### 从 npm (`0.2.6`(中文(简体) )

```sh
pnpm add @contentrail/core@0.2.6 zod@^4.6.7
```

## 定义收藏

```ts
import { defineCollection } from "@contentrail/core";
import { z } from "zod";

const articles = defineCollection({
  name: "articles",
  schema: z.object({
    title: z.string().min(1),
    slug: z.string().min(1),
    published: z.boolean(),
    publishedAt: z.string().optional(),
  }),
});
```

收藏名称必须匹配 `^[a-z][a-z0-9_-]*$`。 。 。 .

### 非预期字段

| `unknownKeys` | 行为 |
| --- | --- |
| `"strip"` (默认) | 未知的根对象密钥被删除 . |
| `"strict"` | 未知的根对象键失败验证 . |

当 schema 是 Zod 对象时, 将应用此策略 。 非对象计划保持不变.

## 验证条目

```ts
import { validateEntry } from "@contentrail/core";

const result = validateEntry(articles, {
  title: "Welcome",
  slug: "welcome",
  published: true,
});

if (!result.success) {
  console.error(result.error.issues);
} else {
  console.log(result.data.title);
}
```

`validateEntry` 永不丢弃无效内容 。 使用 `assertValidEntry` 当你喜欢例外.

## 验证收藏( 条目组)

```ts
import { validateCollection } from "@contentrail/core";

const result = validateCollection(articles, [
  { title: "Welcome", slug: "welcome", published: true },
  { title: "Next", slug: "next", published: false },
]);
```

失败的问题在条目索引中前缀, 例如 `1.title`。 。 。 .

## 类型推论

```ts
import type { InferEntry } from "@contentrail/core";

type Article = InferEntry<typeof articles>;
// { title: string; slug: string; published: boolean; publishedAt?: string }
```

## `ContentSchema`

`ContentSchema` 公共 Zod 4 策略约束 `defineCollection` 编号 : `ContentCollection` 通则. 它的别名是 `z.ZodType` 当地人 `zod` 条目 :

```ts
import { defineCollection, type ContentSchema } from "@contentrail/core";
import { z } from "zod";

const schema: ContentSchema = z.object({
  title: z.string().min(1),
});

const pages = defineCollection({
  name: "pages",
  schema,
});
```

更倾向于用 `z` 并让 `defineCollection` 推断类型; 使用情况 `ContentSchema` 当你需要一个明确的注释.

## 错误

| 错误 | 何时 |
| --- | --- |
| `ContentDefinitionError` | 无效 `defineCollection` 输入( thrown). |
| `ContentValidationError` | 无效的内容( E)`validate*` 结果或 `assertValidEntry`) (中文(简体) ). |

`ContentValidationError` 包括:

-   `collection` — 收藏名称
-   `issues` —— 说 `{ path, code, message, expected?, received? }[]`
-   `toJSON()` - 稳定的可序列形状

## 公共出口

从 `@contentrail/core`数字 :

-   `defineCollection`
-   `validateEntry`
-   `validateCollection`
-   `assertValidEntry`
-   `ContentDefinitionError`
-   `ContentValidationError`
-   类型 : `ContentSchema`, (中文(简体) ), `ContentCollection`, (中文(简体) ), `DefineCollectionInput`, (中文(简体) ), `InferEntry`, (中文(简体) ), `UnknownKeysPolicy`, (中文(简体) ), `ValidationResult`, (中文(简体) ), `ValidationSuccess`, (中文(简体) ), `ValidationFailure`, (中文(简体) ), `ValidationIssue`

有一个单一的浏览器安全导出地图条目( Name`.`) (中文(简体) ). 此软件包中不存在仅服务器的子路径 .

## 兼容性

-   运行时间:任何能够运行Zod的现代无害环境管理环境(浏览器、节点、工人)
-   模块格式:仅限无害环境管理
-   不与Astro、Vite、Cloudflare或反应结合

## 目前的限制

-   无内容 I/O, Git, R2, 或发布 API
-   除了Zod本身之外,没有编辑器的反演帮助
-   没有 JSON Schema 导出
-   需要 Zod 吗 **4.6.7+ (中文(简体) )**; Zod 3 计划不支持
-   参见根 REDME / `docs/PUBLISHING.md` 页:1 `0.2.6` 出版状况

## 常见问题

### @contentrail/core 是什么？

框架独立的ContentRail计划,验证,和内容类型\.

### 如何安装 @contentrail/core？

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

### @contentrail/core 支持 TypeScript 吗？

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

### @contentrail/core 支持 ESM 还是 CommonJS？

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

### @contentrail/core 需要什么版本的 Node\.js？

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

### @contentrail/core 可以商用吗？

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

### @contentrail/core 的下载量有多少？

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

### @contentrail/core 还在维护吗？

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