storyblok-best-practices

Storyblok 最佳实践

这是一份全面的 Storyblok CMS 开发最佳实践指南，面向协助代理开发者的 AI Agent 和大模型。指南包含 24 个类别中的 40 条规则，并按影响程度排序，为自动代码生成和内容架构决策提供指导。

适用场景

在以下场景中参考这些指南：

• 设计 Storyblok 内容模型和组件架构
• 将 Storyblok 与 React、Vue、Nuxt 或 Next.js 集成
• 配置 Visual Editor 和实时预览
• 使用 @storyblok/field-plugin 构建自定义字段插件
• 实现 Content Delivery API 或 Management API
• 使用字段或文件夹翻译配置国际化（i18n）
• 配置用于缓存失效和自动化的 Webhook
• 管理多 Space 架构和 CI/CD 工作流
• 使用自定义解析器处理富文本字段
• 使用 Image Service 优化图像和性能
• 构建工具插件或 Space 插件（侧边栏应用）
• 设置预览和生产环境

按优先级划分的规则类别

优先级	类别	影响	前缀
1	内容建模	CRITICAL	model-
2	SDK 集成	CRITICAL	sdk-
3	Visual Editor	CRITICAL	editor-
4	性能与缓存	CRITICAL	perf-
5	安全与身份验证	CRITICAL	security-
6	字段插件	HIGH	plugin-
7	API 开发	HIGH	api-
8	国际化	HIGH	i18n-
9	Next.js 集成	HIGH	nextjs-
10	Nuxt 集成	HIGH	nuxt-
11	应用开发	HIGH	app-
12	Space 与资源管理	HIGH	space-
13	Webhook 与自动化	MEDIUM-HIGH	webhook-
14	工作流与发布	MEDIUM-HIGH	workflow-
15	CLI 与 DevOps	MEDIUM	cli-
16	测试与质量	MEDIUM	test-
17	富文本与媒体	MEDIUM	richtext-
18	常见模式	HIGH	pattern-
19	SEO 与结构化数据	HIGH	seo-
20	电子商务集成	HIGH	ecommerce-
21	内容迁移	MEDIUM-HIGH	migration-
22	AI 功能	MEDIUM	ai-
23	协作	MEDIUM	collaboration-
24	自定义应用	MEDIUM	app-

快速参考

1. 内容建模（CRITICAL）

• model-component-structure - 遵循组件的原子设计原则
• model-field-configuration - 配置带验证的字段类型
• model-block-nesting - 使用限制管理区块嵌套
• model-naming-conventions - 使用一致的命名方式（snake_case）

2. SDK 集成（CRITICAL）

• sdk-storyblok-editable - 始终对组件应用 storyblokEditable()
• sdk-component-registration - 全局注册所有组件
• sdk-richtext-rendering - 使用自定义解析器渲染富文本

3. Visual Editor（CRITICAL）

• editor-bridge-setup - 正确配置 Storyblok Bridge
• editor-draft-published - 正确处理草稿和已发布内容

4. 性能与缓存（CRITICAL）

• perf-image-optimization - 使用 Image Service 优化内容交付
• perf-cache-invalidation - 使用 cv 参数实现恰当的缓存失效
• perf-monitoring - 监控 API 和内容性能

5. 安全与身份验证（CRITICAL）

• security-token-handling - 安全管理 API 令牌
• security-roles-permissions - 配置基于角色的访问控制（RBAC）和权限

6. 字段插件（HIGH）

• plugin-field-development - 使用 @storyblok/field-plugin SDK 构建字段插件

7. API 开发（HIGH）

• api-content-delivery - 正确使用 Content Delivery API 并进行分页
• api-graphql - 使用 GraphQL API 优化查询
• api-management - 使用 Management API 执行 CRUD 操作

8. 国际化（HIGH）

• i18n-field-translation - 正确实现字段级翻译
• i18n-folder-level - 使用 Dimensions 应用实现文件夹级翻译

9. Next.js 集成（高）

• nextjs-app-router - 与 Next.js App Router 和 RSC 集成

10. Nuxt 集成（高）

• nuxt-integration - 正确配置 @storyblok/nuxt 模块

11. 应用开发（高）

• app-tool-plugins - 使用 App Bridge 构建工具插件和空间插件

12. 空间与资源管理（高）

• space-asset-management - 整理资源和数据源
• space-multi-environment - 面向企业的多空间架构

13. Webhook 与自动化（中高）

• webhook-configuration - 为内容事件配置 Webhook

14. 工作流与发布（中高）

• workflow-releases - 使用 Releases 进行定时发布
• workflow-pipelines - 使用 Pipeline 阶段暂存内容

15. CLI 与 DevOps（中）

• cli-component-sync - 使用 CLI 管理组件架构

16. 测试与质量（中）

• test-preview-environments - 设置预览环境和生产环境
• test-unit-integration - 单元测试、集成测试和 E2E 测试策略

17. 富文本与媒体（中）

• richtext-media-handling - 正确处理富文本媒体

18. 常见模式（高）

• pattern-typescript - 生成和使用 TypeScript 类型
• pattern-error-handling - 实现健壮的错误处理
• pattern-debugging - 调试与故障排除指南
• pattern-relations-references - Story 链接、关系和引用解析

19. SEO 与结构化数据（高）

• seo-structured-data - 配置 JSON-LD、Open Graph 和站点地图

20. 电商集成（高）

• ecommerce-integration - 电商平台集成模式

21. 内容迁移（中高）

• migration-patterns - 内容迁移策略和工具

22. AI 功能（中）

• ai-content-features - Storyblok AI 功能和 RAG 准备

23. 协作（中）

• collaboration-realtime - 实时编辑、评论和冲突解决

24. 自定义应用（中）

• app-custom-sidebar - 字段插件以外的侧边栏应用和工具插件

核心原则

可视化编辑器优先

Storyblok 的可视化编辑器是主要的编辑体验：

• 始终为组件应用 storyblokEditable()
• 配置 Storyblok Bridge 以支持实时编辑
• 在可视化编辑器中测试组件，而不只是检查代码

内容交付 API 与管理 API

API	用途	令牌	缓存
内容交付	获取内容	公开/预览	CDN
管理	CRUD 操作	个人/OAuth	无
GraphQL	只读查询	公开/预览	CDN

框架集成

框架	SDK	特殊功能
React	@storyblok/react (v5+)	useStoryblokState、RSC 支持、StoryblokServerComponent
Vue	@storyblok/vue	v-editable 指令
Nuxt	@storyblok/nuxt (v9+ for Nuxt 4)	自动注册、useAsyncStoryblok、deep 选项
Next.js	@storyblok/react	Draft mode、ISR、App Router
Astro	@storyblok/astro	混合渲染

令牌安全

切勿在客户端代码中公开以下令牌：

• 预览令牌（显示草稿内容）
• 个人访问令牌（具有完整写入权限）
• OAuth 令牌（具有受限范围的访问权限）

可在客户端安全使用：

• 公开令牌（只读已发布内容）

使用方法

阅读各规则文件，了解详细说明和代码示例：

rules/model-component-structure.md
rules/sdk-storyblok-editable.md
rules/editor-bridge-setup.md
rules/perf-image-optimization.md
rules/security-token-handling.md

每个规则文件都包含：

• 对其重要性的简要说明
• 错误代码示例及说明
• 正确代码示例及说明
• 配置表和参考资料

Key Resources

• Storyblok Documentation
• React SDK
• Nuxt Module
• Field Plugin SDK
• Storyblok CLI
• Content Delivery API
• Management API