新格式示例：从 Block 到组件库

Q: 如何迁移现有文章？

我们提供了自动迁移脚本 npm run migrate-blocks ，可以批量转换文章格式。也可以手动逐个迁移。

Q: 组件如何传递参数？

使用标准的 MDX props 语法： <Hero color="gradient-ocean" fullscreen> 。IDE 会提供自动补全和类型检查。

欢迎使用组件库方案

告别复杂的 Block 系统，使用标准 MDX 组件创作内容！

主要优势：

✅ 标准 MDX 语法，IDE 完整支持
✅ TypeScript 类型检查和自动补全
✅ 组件独立，职责清晰
✅ 代码减少 74%，更易维护

🎯 简洁明了

使用标准 MDX 组件语法，清晰易懂，不会再出现解析错误。

📦 开发体验

IDE 自动补全、类型检查、语法高亮，开发效率大幅提升。

🔧 易于调试

组件独立，错误提示清晰，快速定位问题所在。

格式对比

旧格式（Block 系统）

旧格式使用 HTML 注释定义 Block 元数据，需要复杂的解析逻辑：

<!-- BLOCK: hero, color: gradient-ocean -->
## Block 标题

内容...
<!-- /BLOCK -->

<!-- BLOCK: standard -->
## 下一个 Block
内容...
<!-- /BLOCK -->

问题：

需要 2500+ 行解析代码
HTML 注释语法不直观
IDE 无法提供自动补全
调试困难，错误信息模糊

新格式（组件库）

新格式使用标准 MDX 组件，简洁直观：

import Hero from '@/components/flow/Hero.astro';

<Hero color="gradient-ocean" fullscreen>
  ## 标题

  内容...
</Hero>

## 普通 Markdown 段落

这是普通的 Markdown 内容，不需要包裹在任何组件中。

优势：

只需 650 行组件代码
标准 MDX 语法
IDE 完整支持（自动补全、类型检查）
错误提示清晰

设计理念

简单、明确、可靠。用最少的代码，实现最强的功能。

— FlowPage 2.0 Team

📉

74%

代码减少

✅

100%

向后兼容

⚡

开发效率

🛡️

破坏性变更

旧文章需要立即迁移吗？

不需要！你可以按自己的节奏逐步迁移，新旧格式可以共存。

新格式支持所有功能吗？

是的！所有原有功能都通过组件实现，功能完全一致且更强大。

如何迁移现有文章？

我们提供了自动迁移脚本 npm run migrate-blocks，可以批量转换文章格式。也可以手动逐个迁移。

组件如何传递参数？

使用标准的 MDX props 语法：<Hero color="gradient-ocean" fullscreen>。IDE 会提供自动补全和类型检查。

如何使用新格式创作内容

1

导入需要的组件

在 MDX 文件开头导入组件：import Hero from '@/components/flow/Hero.astro'
2

使用组件包裹内容

用 JSX 语法包裹内容：<Hero color="gradient-blue">...</Hero>
3

添加普通 Markdown

普通段落直接写 Markdown，不需要任何包裹。标题、列表、代码块都可以正常使用。
4

预览和调试

运行 npm run dev，IDE 会提供完整的类型检查和错误提示。

技术细节

组件库架构

所有组件位于 src/components/flow/ 目录：

Hero.astro - 全屏大图展示
Quote.astro - 引用卡片
Stats.astro - 数据统计展示
Cards.astro - 卡片网格布局
Gallery.astro - 图片画廊
FAQ.astro - 常见问答（带 SEO Schema）
HowTo.astro - 操作指南（带 SEO Schema）
Review.astro - 产品评测

路径别名配置

在 tsconfig.json 中配置路径别名：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["src/components/*"]
    }
  }
}

这样可以使用 @/components/flow/Hero.astro 代替相对路径 ../../../src/components/flow/Hero.astro。

SEO 优化

FAQ 和 HowTo 组件自动生成 JSON-LD 结构化数据：

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [...]
}

这有助于 Google 显示富媒体搜索结果（Rich Results）。

组件库方案

5 / 5

优点

代码量减少 74%，从 2500 行降至 650 行
标准 MDX 语法，IDE 完整支持
TypeScript 类型检查，开发更安全
组件独立，职责清晰，易于维护
SEO 友好，自动生成结构化数据
错误提示清晰，调试效率高

缺点

需要在文件开头导入组件（但这是标准做法）
旧文章需要迁移（提供自动化脚本）

总结

组件库方案完美解决了 Block 系统的复杂性问题，同时保持了所有功能。代码更简洁、开发体验更好、维护成本更低。强烈推荐在所有新文章中使用！

评测者: FlowPage Team 日期: 2025-11-12

下一步行动

现在你可以：

浏览组件文档 - 查看 src/components/flow/ 目录中的组件
创建新文章 - 使用新的组件库格式
迁移旧文章 - 运行 npm run migrate-blocks（即将推出）
提供反馈 - 告诉我们你的使用体验

拥抱标准，化繁为简

FlowPage 2.0 回归 MDX 标准，用组件库替代自定义解析，让创作更简单、更可靠。