# 内容收藏 **状态**：生产就绪 ✅ **最后更新**：2025-11-07 **依赖项**：无 **最新版本**：@content-collections/core@0.12.0、@content-collections/vite@0.2.7、zod@3.23.8 ** ** ## 什么是内容集？ Content Collections 将本地内容文件 (Markdown/MDX) 转换为**类型安全的 TypeScript 数据**，并在构建时自动验证。 **它解决的问题**：手动内容解析、缺乏类型安全、无效 frontmatter 导致的运行时错误。 **它是如何工作的**： 1. 在`content-collections.ts`中定义集合（名称、目录、Zod schema） 2. CLI/插件扫描文件系统，解析 frontmatter，根据模式进行验证 3. 在 `.content-collections/ generated/` 中生成 TypeScript 模块 4. 导入集合：`import { allPosts } from "content-collections"` **非常适合**：博客、文档网站、包含 Cloudflare Workers、Vite、Next.js 的内容丰富的应用程序。 ** ** ## 快速入门（5 分钟） ### 1\.安装依赖项 pnpm add -D @content-collections/core @content-collections/vite zod ### 2\.配置 TypeScript 路径别名添加到`tsconfig.json`： { “编译器选项”：{ “路径”：{ “内容集合”：[“./.内容集合/生成”] } } } ### 3.配置Vite插件添加到`vite.config.ts`：从“vite”导入{defineConfig}；从“@vitejs/plugin-react”导入反应；从“@content-collections/vite”导入内容集合；导出默认的defineConfig({ 插件：[ 反应（）， contentCollections(), // 必须在react()之后 ], }); ### 4\.更新.gitignore .内容集合/ ### 5\.创建集合配置在项目根目录中创建“content-collections.ts”：从“@content-collections/core”导入{defineCollection，defineConfig}；从“zod”导入{z}； const posts = DefineCollection({ 名称：“帖子”，目录：“内容/帖子”，包括：“*.md”，架构： z.object({ 标题: z.string(), 日期：z.string(), 描述：z.string(), 内容：z.string(), }), }); 导出默认的defineConfig({ 收藏：[帖子]， }); ### 6\.创建内容目录 mkdir -p 内容/帖子创建 `content/posts/first-post.md`： --- 标题：我的第一篇文章日期：2025-11-07 描述：内容集合简介 --- # 我的第一篇文章内容在这里... ### 7\.导入与使用从“内容集合”导入 { allPosts }； console.log(allPosts); // 完全输入！ **结果**：具有自动完成、验证和 HMR 功能的类型安全内容。 ** ** ## 关键规则 ### ✅ 始终这样做： 1. **将路径别名添加到 tsconfig.json** \- 导入工作所需 2. **将 .content-collections 添加到 .gitignore** \- 不应提交生成的文件 3. **使用标准模式验证器** \- 支持 Zod、Valibot、ArkType 4. **在 schema 中包含 `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：找不到模块：“内容集合” **错误**：“找不到模块“内容集合”或其相应的类型声明” **为什么会发生**：缺少 TypeScript 路径别名配置。 **预防**：添加到`tsconfig.json`： { “编译器选项”：{ “路径”：{ “内容集合”：[“./.内容集合/生成”] } } } 在 VS Code 中重新启动 TypeScript 服务器：`Cmd+Shift+P`→“TypeScript：重新启动 TS Server” **来源**：常见用户错误 ** ** ### 问题#2：Vite 不断重启循环 **错误**：开发服务器不断重启，无限循环。 **为什么会发生**：Vite 观看 `.content-collections` 目录更改，这会触发重新生成。 **预防**： 1. 添加到`.gitignore`： .内容集合/ 2. 添加到`vite.config.ts`（如果仍然发生）：导出默认的defineConfig({ 服务器：{ 观看：{ 忽略：[“**/.content-collections/**”]， }, }, }); **来源**：GitHub 问题 #591（TanStack 启动） ** ** ### 问题 #3：未反映转换类型 **错误**：TypeScript 类型与转换后的文档不匹配。 **为什么会发生**：TypeScript 不会自动推断转换函数的返回类型。 **预防**：显式输入您的转换返回值： const posts = DefineCollection({ 名称：“帖子”， // ... 架构 transform: (post): PostWithSlug => ({ // 输入返回值！ ...帖子， slug: post._meta.path.replace(/\.md$/, ""), }), }); 类型 PostWithSlug = { // ... 模式字段 slug：字符串； }; **来源**：GitHub 问题 #396 ** ** ### 问题 #4：文件更改时集合未更新 **错误**：新内容文件未出现在集合中。 **为什么会发生**：Glob 模式不匹配，或者开发服务器需要重新启动。 **预防**： 1. 验证 glob 模式是否与您的文件匹配： include: "*.md" // 仅根文件 include: "**/*.md" // 所有嵌套文件 include: "posts/*.md" // 仅 posts/ 文件夹 2. 在监视模式之外添加新文件后重新启动开发服务器 3.检查实际保存的文件（注意编辑器问题） **来源**：常见用户错误 ** ** ### 问题 #5：Shiki 的 MDX 类型错误 **错误**：`esbuild 错误，带有 shiki langAlias` 或编译失败。 **为什么会发生**：Shiki 和 Content Collections 之间的版本不兼容。 **预防**：使用兼容版本： { “开发依赖项”：{ "@content-collections/mdx": "^0.2.2", "shiki": "^1.0.0" } } 在升级 Shiki 之前，请检查文档中的官方兼容性矩阵。 **来源**：GitHub 问题 #598 (Next.js 15) ** ** ### 问题 #6：MDX 导入中的自定义路径别名失败 **错误**：使用“@”别名的 MDX 导入无法解析。 **为什么会发生**：MDX 编译器不考虑 tsconfig 路径别名。 **预防**：在 MDX 导入中使用相对路径：从“@/components/Component”导入组件从“../../components/Component”导入组件或者配置文件附加程序（高级，请参阅references/transform-cookbook.md）。 **来源**：GitHub 问题 #547 ** ** ### 问题 #7：验证错误消息不明确 **错误**：神秘的 Zod 验证错误，例如“预期字符串，收到未定义”。 **为什么会发生**：Zod 错误未针对内容上下文进行格式化。 **预防**：将自定义错误消息添加到架构中：架构： z.object({ 标题：z.string({ required_error: "frontmatter 中需要标题", invalid_type_error: "标题必须是字符串", }), 日期： z.string().refine( (val) => !isNaN(Date.parse(val)), “日期必须是有效的 ISO 日期 (YYYY-MM-DD)” ), }) **来源**：GitHub 问题 #403 ** ** ### 问题 #8：Ctrl+C 不会停止进程 **错误**：开发进程在退出时挂起，需要“kill -9”。 **为什么会发生**：文件观察器无法正确清理。 **预防**：这是观察者的一个已知问题。解决方法： 1.挂起时使用`kill -9 ` 2. 单独使用“content-collections watch”（而不是插件）进行更多控制 3. 在`vite.config.ts`中添加清理处理程序（高级） **来源**：GitHub 问题 #546 ** ** ## 配置模式 ### 基本博客集合从“@content-collections/core”导入{defineCollection，defineConfig}；从“zod”导入{z}； const posts = DefineCollection({ 名称：“帖子”，目录：“内容/帖子”，包括：“*.md”，架构： z.object({ 标题: z.string(), 日期：z.string(), 描述：z.string(), 标签：z.array(z.string()).可选(), 内容：z.string(), }), }); 导出默认的defineConfig({ 收藏：[帖子]， }); ** ** ### 多集合设置 const posts = DefineCollection({ 名称：“帖子”，目录：“内容/帖子”，包括：“*.md”，架构： z.object({ 标题: z.string(), 日期：z.string(), 描述：z.string(), 内容：z.string(), }), }); const 文档 = 定义集合({ 名称：“文档”，目录：“内容/文档”， include: "**/*.md", // 嵌套文件夹架构： z.object({ 标题: z.string(), 类别： z.string(), 顺序：z.number().可选()，内容：z.string(), }), }); 导出默认的defineConfig({ 集合：[帖子，文档]， }); ** ** ### 转换函数（计算字段） const posts = DefineCollection({ 名称：“帖子”，目录：“内容/帖子”，包括：“*.md”，架构： z.object({ 标题: z.string(), 日期：z.string(), 内容：z.string(), }), 变换：（后）=>（{ ...帖子， slug: post._meta.path.replace(/\.md$/, ""), 阅读时间：Math.ceil(post.content.split(/\s+/).length / 200), 年：新日期（post.date）.getFullYear（）， }), }); ** ** ### MDX 与 React 组件从“@content-collections/mdx”导入{compileMDX}； const posts = DefineCollection({ 名称：“帖子”，目录：“内容/帖子”，包括：“*.mdx”，架构： z.object({ 标题: z.string(), 日期：z.string(), 内容：z.string(), }), 转换：异步（后）=> { const mdx = 等待compileMDX(post.content, { 语法荧光笔：“shiki”，式选项：{ 主题：“github-dark”， }, }); 返回{ ...帖子， mdx, slug: post._meta.path.replace(/\.mdx$/, ""), }; }, }); ** ** ## React 组件集成 ### 在 React 中使用集合从“内容集合”导入 { allPosts }；导出函数 BlogList() { 返回（

{帖子.标题}

{帖子描述}
<时间>{post.date}

）； } ** ** ### 渲染 MDX 内容从“@content-collections/mdx/react”导入{MDXContent}；导出函数 BlogPost({ post }: { post: { mdx: string } }) { 返回（ <文章> ）； } ** ** ## Cloudflare Worker 部署 Content Collections **非常适合 Cloudflare Workers** 因为： * 仅构建时（无运行时文件系统访问） * 输出静态JavaScript模块 * 生成的代码中没有 Node.js 依赖项 ### 部署模式本地开发 → 内容集合构建 → vite 构建 → wrangler 部署 ### 牧马人.toml 名称 =“我的内容网站” 兼容性_日期=“2025-11-07” [资产] 目录=“./dist” 绑定=“资产” ### 构建脚本 `package.json`: { “脚本”：{ "dev": "vite", "build": "vite 构建", “部署”：“pnpm构建&&牧马人部署” } } **注意**：Vite 插件自动处理“内容集合构建”！ ** ** ## 使用捆绑资源 ### 模板（模板/）复制粘贴准备好的配置文件： * `content-collections.ts` \- 基本博客设置 * `content-collections-multi.ts` \- 多个集合 * `content-collections-mdx.ts` \- 带语法高亮的 MDX * `tsconfig.json` \- 完整的 TypeScript 配置 * `vite.config.ts` \- Vite 插件设置 * `blog-post.md` \- 示例内容文件 * `BlogList.tsx` \- React 列表组件 * `BlogPost.tsx` \- React MDX 渲染组件 * `wrangler.toml` \- Cloudflare Workers 配置 ### 参考文献（参考文献/）高级主题的深入文档： * `schema-patterns.md` \- 常见的 Zod 模式模式 * `transform-cookbook.md` \- 转换函数食谱 * `mdx-components.md` \- MDX + React 集成 * `deployment-guide.md` \- Cloudflare Workers 设置 **何时加载**：当您需要基本设置之外的高级模式时，Claude 应该加载这些。 ### 脚本（脚本/） * `init-content-collections.sh` \- 一命令自动设置 ** ** ## 依赖关系 ### 必填 { “开发依赖项”：{ "@content-collections/core": "^0.12.0", "@content-collections/vite": "^0.2.7", "zod": "^3.23.8" } } ### 可选（MDX） { “开发依赖项”：{ "@content-collections/markdown": "^0.1.4", "@content-collections/mdx": "^0.2.2", "shiki": "^1.0.0" } } ** ** ## 官方文档 * **官方网站**： * **文档**： * **GitHub**： * **Vite 插件** : * **MDX 集成** ： ** ** ## 软件包版本（2025-11-07 验证）套餐 |版本 |状态 ---|---|--- @内容集合/核心 | 0.12.0 | ✅ 最新稳定版 @content-collections/vite | 0.2.7 | 0.2.7 ✅ 最新稳定版 @内容集合/mdx | 0.2.2 | ✅ 最新稳定版 @内容集合/markdown | 0.1.4 | 0.1.4 ✅ 最新稳定版佐德 | 3.23.8 | ✅ 最新稳定版 ** ** ## 故障排除 ### 问题：TypeScript 找不到“内容集合” **解决办法** : 在 `tsconfig.json` 中添加路径别名，重启 TS 服务器。 ** ** ### 问题：Vite 不断重启 **解决方案**：将`.content-collections/`添加到`.gitignore`并Vite监视忽略。 ** ** ### 问题：更改未反映出来 **解决方案**：重新启动开发服务器，验证 glob 模式，检查保存的文件。 ** ** ### 问题：MDX 编译错误 **解决方案**：检查Shiki版本兼容性，验证MDX语法。 ** ** ### 问题：验证错误不清楚 **解决方案**：将自定义错误消息添加到 Zod 架构中。 ** ** ## 完整设置清单 * 安装了 `@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组件中导入的集合 * 验证类型有效（自动完成） * 测试热重载（更改内容文件） ** ** **问题？有问题吗？** 1. 检查 `references/` 目录以进行深入研究 2. 验证 tsconfig.json 中的路径别名 3. 检查Vite插件顺序（react()之后） 4. 查看上述已知问题 5.查看官方文档：

{帖子.标题}

内容集

包含技能