内容集合工具 content-collections

---

名称: content-collections 描述: Content Collections 是一个以 TypeScript 为先的构建工具，用于 Markdown/MDX 内容。适用于博客、文档、内容站点，配合 Vite + React、MDX 组件、类型安全的 Zod 模式、Contentlayer 迁移，或遇到 TypeScript 导入错误、路径别名问题、集合验证错误。

关键词: content-collections, @content-collections/core, @content-collections/vite, @content-collections/mdx, MDX, markdown, Zod 模式验证, 类型安全内容, frontmatter, compileMDX, defineCollection, defineConfig, Vite 插件, tsconfig 路径, .content-collections/generated, MDXContent 组件, rehype 插件, remark 插件, 内容模式, 文档转换, allPosts 导入, 静态站点生成, 博客设置, 文档, Cloudflare Workers 静态资源, 内容验证错误, 模块未找到 content-collections, 路径别名不工作, MDX 类型错误, 转换函数异步, 集合未更新 许可证: MIT

Content Collections

状态: 生产就绪 ✅ 最后更新: 2025-11-07 依赖项: 无 最新版本: @content-collections/core@0.12.0, @content-collections/vite@0.2.7, zod@3.23.8

---

什么是 Content Collections？

Content Collections 将本地内容文件（Markdown/MDX）转换为类型安全的 TypeScript 数据，并在构建时自动验证。

解决的问题: 手动内容解析、缺乏类型安全、无效 frontmatter 导致的运行时错误。

工作原理:

1. 在 content-collections.ts 中定义集合（名称、目录、Zod 模式）
2. CLI/插件扫描文件系统，解析 frontmatter，根据模式验证
3. 在 .content-collections/generated/ 中生成 TypeScript 模块
4. 导入集合：import { allPosts } from "content-collections"

完美适用于: 博客、文档站点、内容密集型应用，如 Cloudflare Workers、Vite、Next.js。

---

快速开始（5 分钟）

1. 安装依赖项

# Bun（推荐）
bun add -d @content-collections/core @content-collections/vite zod

# npm
npm install -D @content-collections/core @content-collections/vite zod

# pnpm
pnpm add -D @content-collections/core @content-collections/vite zod

2. 配置 TypeScript 路径别名

添加到 tsconfig.json：

{
  "compilerOptions": {
    "paths": {
      "content-collections": ["./.content-collections/generated"]
    }
  }
}

3. 配置 Vite 插件

添加到 vite.config.ts：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import contentCollections from "@content-collections/vite";

export default defineConfig({
  plugins: [
    react(),
    contentCollections(), // 必须在 react() 之后
  ],
});

4. 更新 .gitignore

.content-collections/

5. 创建集合配置

在项目根目录创建 content-collections.ts：

import { defineCollection, defineConfig } from "@content-collections/core";
import { z } from "zod";

const posts = defineCollection({
  name: "posts",
  directory: "content/posts",
  include: "*.md",
  schema: z.object({
    title: z.string(),
    date: z.string(),
    description: z.string(),
    content: z.string(),
  }),
});

export default defineConfig({
  collections: [posts],
});

6. 创建内容目录

mkdir -p content/posts

创建 content/posts/first-post.md：

---
title: 我的第一篇文章
date: 2025-11-07
description: Content Collections 简介
---

# 我的第一篇文章

内容在这里...

7. 导入和使用

import { allPosts } from "content-collections";

console.log(allPosts); // 完全类型安全！

结果: 类型安全内容，支持自动完成、验证和热重载。

---

关键规则

✅ 必须做：

1. 添加路径别名到 tsconfig.json - 导入工作所必需
2. 添加 .content-collections 到 .gitignore - 生成文件不应提交
3. 使用标准模式验证器 - 支持 Zod、Valibot、ArkType
4. 在模式中包含 content 字段 - frontmatter 解析所必需
5. 在转换中等待 compileMDX - MDX 编译是异步的
6. 在 Vite 中将 contentCollections() 放在 react() 之后 - 插件顺序重要

❌ 禁止做：

1. 提交 .content-collections 目录 - 始终生成，从不提交
2. 使用非标准验证器 - 必须支持 StandardSchema 规范
3. 忘记在配置更改后重启开发服务器 - 新集合所必需
4. 使用同步转换与异步操作 - 转换必须是异步的
5. 双重包装路径别名 - 使用 content-collections 而非 ./content-collections
6. 从错误包导入 - @content-collections/core 用于配置，content-collections 用于数据

---

已知问题预防

问题 #1: 模块未找到: ‘content-collections’

错误: Cannot find module 'content-collections' or its corresponding type declarations

原因: 缺少 TypeScript 路径别名配置。

预防:

添加到 tsconfig.json：

{
  "compilerOptions": {
    "paths": {
      "content-collections": ["./.content-collections/generated"]
    }
  }
}

在 VS Code 中重启 TypeScript 服务器：Cmd+Shift+P → “TypeScript: Restart TS Server”

来源: 常见用户错误

---

问题 #2: Vite 持续重启循环

错误: 开发服务器持续重启，无限循环。

原因: Vite 监视 .content-collections 目录变化，触发重新生成。

预防:

1. 添加到 .gitignore：

.content-collections/

2. 添加到 vite.config.ts（如果仍发生）：

export default defineConfig({
  server: {
    watch: {
      ignored: ["**/.content-collections/**"],
    },
  },
});

来源: GitHub Issue #591 (TanStack Start)

---

问题 #3: 转换类型未反映

错误: TypeScript 类型不匹配转换后的文档。

原因: TypeScript 不自动推断转换函数返回类型。

预防:

显式类型化转换返回：

const posts = defineCollection({
  name: "posts",
  // ... 模式
  transform: (post): PostWithSlug => ({ // 类型化返回！
    ...post,
    slug: post._meta.path.replace(/\.md$/, ""),
  }),
});

type PostWithSlug = {
  // ... 模式字段
  slug: string;
};

来源: GitHub Issue #396

---

问题 #4-8: 高级故障排除

更多问题在 references/advanced-troubleshooting.md 中涵盖：

问题	错误	快速修复
#4	集合未更新	验证 glob 模式，重启开发服务器
#5	MDX/Shiki 错误	使用兼容版本（shiki ^1.0.0）
#6	MDX 路径别名失败	在 MDX 导入中使用相对路径
#7	验证错误不清晰	添加自定义 Zod 错误消息
#8	Ctrl+C 不停止	使用 kill -9 或单独监视命令

---

配置模式

模式	使用场景	模板
基本博客	单个集合，仅 Markdown	templates/content-collections.ts
多集合	帖子 + 文档，嵌套文件夹	templates/content-collections-multi.ts
转换函数	计算字段（slug、阅读时间）	参见 references/transform-cookbook.md
MDX + React	语法高亮、React 组件	templates/content-collections-mdx.ts

详细模式模式（日期、标签、验证），加载 references/schema-patterns.md。

---

React 组件集成

在 React 中使用集合

import { allPosts } from "content-collections";

export function BlogList() {
  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post._meta.path}>
          <h2>{post.title}</h2>
          <p>{post.description}</p>
          <time>{post.date}</time>
        </li>
      ))}
    </ul>
  );
}

---

渲染 MDX 内容

import { MDXContent } from "@content-collections/mdx/react";

export function BlogPost({ post }: { post: { mdx: string } }) {
  return (
    <article>
      <MDXContent code={post.mdx} />
    </article>
  );
}

---

Cloudflare Workers 部署

Content Collections 完美适用于 Cloudflare Workers（仅构建时，无运行时文件系统）。使用模板 templates/wrangler.toml 配置。

模式: vite build → wrangler deploy（Vite 插件自动处理 content-collections）

详细部署指南，加载 references/deployment-guide.md。

---

捆绑资源

模板（9 个复制粘贴文件）

content-collections.ts, content-collections-multi.ts, content-collections-mdx.ts, tsconfig.json, vite.config.ts, BlogList.tsx, BlogPost.tsx, blog-post.md, wrangler.toml

脚本

init-content-collections.sh - 一键自动化设置

---

依赖项

必需

{
  "devDependencies": {
    "@content-collections/core": "^0.12.0",
    "@content-collections/vite": "^0.2.7",
    "zod": "^3.23.8"
  }
}

可选（MDX）

{
  "devDependencies": {
    "@content-collections/markdown": "^0.1.4",
    "@content-collections/mdx": "^0.2.2",
    "shiki": "^1.0.0"
  }
}

---

官方文档

• 官方网站: https://www.content-collections.dev
• 文档: https://www.content-collections.dev/docs
• GitHub: https://github.com/sdorra/content-collections
• Vite 插件: https://www.content-collections.dev/docs/vite
• MDX 集成: https://www.content-collections.dev/docs/mdx

---

包版本（已验证 2025-11-07）

包	版本	状态
@content-collections/core	0.12.0	✅ 最新稳定
@content-collections/vite	0.2.7	✅ 最新稳定
@content-collections/mdx	0.2.2	✅ 最新稳定
@content-collections/markdown	0.1.4	✅ 最新稳定
zod	3.23.8	✅ 最新稳定

---

快速故障排除

问题	解决方案
TypeScript 找不到模块	添加路径别名到 tsconfig.json，重启 TS 服务器
Vite 持续重启	添加 .content-collections/ 到 .gitignore
更改未反映	重启开发服务器，验证 glob 模式
MDX 编译错误	检查 Shiki 版本兼容性
验证错误不清晰	添加自定义 Zod 错误消息

---

何时加载参考

参考	加载当…
schema-patterns.md	设置复杂模式、日期验证、可选字段时
transform-cookbook.md	添加计算字段、异步转换、slug 时
mdx-components.md	在 MDX 中集成 React 组件、语法高亮时
deployment-guide.md	部署到 Cloudflare Workers 或其他平台时
advanced-troubleshooting.md	问题 #4-8（文件监视、路径别名、进程挂起）时

---

完整设置检查列表

• [ ] 安装 @content-collections/core 和 @content-collections/vite
• [ ] 安装 zod 用于模式验证
• [ ] 添加路径别名到 tsconfig.json
• [ ] 添加 contentCollections() 到 vite.config.ts（在 react() 之后）
• [ ] 添加 .content-collections/ 到 .gitignore
• [ ] 在项目根目录创建 content-collections.ts
• [ ] 创建内容目录（例如 content/posts/）
• [ ] 使用 Zod 模式定义集合
• [ ] 创建第一个带 frontmatter 的内容文件
• [ ] 在 React 组件中导入集合
• [ ] 验证类型工作（自动完成）
• [ ] 测试热重载（更改内容文件）