如何在 Next.js 应用中添加 shadcn 图表而无需编写 Recharts 样板代码
内容提要
ChartCN 是一个免费开源的 shadcn 图表生成器，支持粘贴数据、选择图表并复制单个 TSX 文件，仅依赖 shadcn/ui 图表组件和 Recharts 3。教程演示在 Next.js 中生成收入与支出柱状图：初始化 shadcn/ui、添加图表组件、生成代码、接入页面，并通过 Server Component 传入实时数据。颜色由 CSS 变量经 chartConfig 流转，自动适配深色模式；null 值显示为数据缺口。
延伸解读
ChartCN 的定位：生成器而非组件库
ChartCN 是一个免费开源的 shadcn 图表生成器，它不提供运行时包，而是让你粘贴数据、选择图表后复制一个独立的 TSX 文件。该文件仅依赖 shadcn/ui 图表组件和 Recharts 3，因此项目无需安装或同步额外的 ChartCN 包。生成器支持 13 种图表类型，包括柱状图、折线图、饼图等，所有图表都遵循相同的“粘贴、选择、复制”工作流。
颜色主题的流转机制
在 shadcn/ui 图表中，颜色通过 CSS 变量和 chartConfig 对象流转。初始化 shadcn/ui 时会在 globals.css 中定义 --chart-1 到 --chart-5 五个变量，并分别设置亮色和暗色模式的值。chartConfig 将数据键映射到这些变量，ChartContainer 再为每个键生成作用域内的 --color-<key> 变量。因此，修改一个 CSS 变量即可全局调整图表颜色，且暗色模式自动适配。
服务端数据与 null 值的处理
对于真实数据，建议在 Server Component 中加载数据，然后将类型化的行数据作为 prop 传递给客户端图表组件。这样数据库凭证和 API 密钥保留在服务端。生成的类型将数值系列定义为 number | null，因为真实数据常有缺失。null 值会渲染为数据缺口，而不是零值柱，从而避免误导性的可视化。
常见陷阱与规避方法
使用 ChartCN 时需注意几个常见问题：确保安装 Recharts 3，否则会出现类型错误；不要将生成的 chart.tsx 覆盖 components/ui/chart.tsx，否则所有图表会失效；每个生成的组件都默认导出为 Chart，在同一页面使用多个图表时需在导入时重命名。此外，若图表显示为黑色且图例点缺失，通常是因为 globals.css 中缺少 --chart-1 到 --chart-5 变量。
Q&A
ChartCN 是什么？它和 shadcn/ui 图表组件有什么关系？
ChartCN 是一个免费开源的 shadcn 图表生成器。你粘贴数据、选择图表，然后复制一个 TSX 文件，该文件仅依赖 shadcn/ui 图表组件和 Recharts。它不是一个组件库，没有需要安装或更新的包。
如何在 Next.js 项目中初始化 shadcn/ui 并添加图表组件？
运行 npx shadcn@latest init 初始化 shadcn/ui，它会创建 components.json、添加 lib/utils.ts 并在 app/globals.css 中写入主题变量（包括 --chart-1 到 --chart-5）。然后运行 npx shadcn@latest add chart 来安装 recharts 并创建 components/ui/chart.tsx。
ChartCN 生成图表时，颜色是如何工作的？如何适配深色模式？
颜色通过 CSS 变量流转：shadcn/ui 初始化时在 globals.css 中定义 --chart-1 到 --chart-5，每个变量有亮色和暗色模式的值。在 chartConfig 中，每个数据键映射到一个颜色变量（如 var(--chart-1)）。ChartContainer 会为每个键创建作用域 CSS 变量（如 --color-Revenue），指向主题颜色，因此图表在深色模式下自动切换颜色。
如何将实时数据传递给 ChartCN 生成的图表？
在 ChartCN 中将 Code 选项切换为 Data as prop，复制生成的文件。该文件导出 ChartRow 类型和接受 data 属性的 Chart 组件。然后在 Server Component 中调用异步函数获取数据，并将数据作为 prop 传递给图表组件。数据加载在服务器端进行，只有数据行发送到客户端组件。
ChartCN 生成的图表代码中，null 值如何处理？
null 值在图表中显示为数据缺口，而不是零值的柱子。在 Data as prop 模式下，数据系列类型为 number | null，因此 null 值会渲染为缺失的柱子。
使用 ChartCN 生成的图表时，常见的错误有哪些？如何解决？
常见问题包括：1) 类型错误如 'itemSorter' 不存在，说明安装了 Recharts 2，需运行 npm install recharts@latest 升级到 Recharts 3。2) 柱子变黑且图例点缺失，说明 globals.css 中缺少 --chart-1 到 --chart-5，需重新运行 npx shadcn@latest init 或手动添加。3) 粘贴生成文件覆盖了 components/ui/chart.tsx 导致所有图表失效，需用 npx shadcn@latest add chart --overwrite 恢复，并将生成图表保存到其他文件名。4) 同一页面两个图表同名，因为每个生成组件都导出为 Chart，导入时需重命名。
