从 shadcn/ui 平滑迁移到 SmoothUI完整对照升级指南【免费下载链接】smoothuiSmoothUI is a collection of beautifully designed components with smooth animations built with React, Tailwind CSS, Shadcn/ui and Motion项目地址: https://gitcode.com/gh_mirrors/sm/smoothui如果你正在使用 shadcn/ui 构建 React 应用又想让界面动起来更有质感那么把目光投向SmoothUI会是一个明智的选择。SmoothUI 是一套基于 React、Tailwind CSS、shadcn/ui 与 Motion 打造的动画组件库它保留了 shadcn/ui 的组件化思路与自由度同时为每个组件注入了丝滑的交互动画。本文为你整理了一份从shadcn/ui 迁移到 SmoothUI的完整对照升级指南从环境准备、安装命令到组件对照与常见问题一步步带你平滑过渡全程无需重写整个项目。为什么从 shadcn/ui 迁移到 SmoothUI核心差异对比shadcn/ui 的价值在于复制粘贴、完全可控而 SmoothUI 在此基础上叠加了动画体系。两者的关系并非二选一而是平滑升级SmoothUI 官方就是 shadcn 注册表registry的一部分你完全可以把它当作 shadcn/ui 的动画增强包来使用。对比维度shadcn/uiSmoothUI组件定位基础 UI 组件按钮、卡片、表单带流畅动画的高级组件与页面区块动画支持少量、需要自己写内置 Motion 动画开箱即用安装方式shadcn CLISmoothUI CLI 或 shadcn CLI 均可依赖关系自包含依赖 shadcn/ui 生态自动解析组件数量约 50 基础组件130 动画组件与区块核心结论迁移 SmoothUI不需要移除已有的 shadcn/ui 组件而是新增一层动画组件能力两者可以在同一个项目中和谐共存。迁移前需要准备的环境清单在动手迁移前请先确认你的项目满足以下最低要求避免安装过程中报错✅ Node.js 18.17 或更高版本✅ React 19 或更高版本✅ Tailwind CSS 4 已正确配置✅ 已初始化 shadcn/ui生成components.json✅ 推荐使用 pnpmnpm / yarn / bun 同样支持官方安装步骤详见 getting-started.mdx它覆盖了 Next.js、Vite、Astro、Remix 等多种框架的接入方式。一条命令完成迁移安装两种安装方式任选SmoothUI 作为官方 shadcn 注册表安装体验几乎和 shadcn/ui 一致。你只需要在项目根目录执行一条命令方式一SmoothUI CLI推荐带交互式选择npx smoothui-clilatest add smooth-button不带组件名时进入交互模式可以搜索、筛选并批量选择组件npx smoothui-clilatest add npx smoothui-clilatest list方式二shadcn CLI老用户零学习成本npx shadcnlatest add smoothui/smooth-button两种方式都会自动完成三件事下载组件源码、安装motion等依赖、解析/路径别名。安装后的组件统一存放在components/smoothui/ui/目录下与原有 shadcn/ui 组件互不干扰。迁移后组件如何对照使用新旧组件映射表这是本次迁移指南的重头戏。下表整理了常见 shadcn/ui 组件与 SmoothUI 动画版本的一一对照关系方便你按需替换shadcn/ui 基础组件SmoothUI 动画升级版应用场景ButtonSmoothButton带按压缩放与悬停反馈的按钮AccordionBasicAccordionFAQ、可折叠内容区TabsAnimatedTabs滑动指示条切换标签InputAnimatedInput带聚焦动画的输入框DialogDynamicIsland灵动岛风格弹层ProgressAnimatedProgressBar加载进度动画AvatarAnimatedAvatarGroup头像堆叠动画CardExpandableCards可展开卡片布局以手风琴组件为例安装后直接按 shadcn/ui 的使用习惯导入即可import BasicAccordion from /components/smoothui/ui/BasicAccordion; export default function FAQ() { return ( BasicAccordion items{[ { id: 1, title: 迁移成本高吗, content: p只需新增组件无需删改旧代码。/p }, { id: 2, title: 支持暗色模式吗, content: pSmoothUI 组件开箱即支持明暗双主题。/p }, ]} / ); }所有组件源码都可以在 packages/smoothui/components/ 目录中直接查看与二次定制真正保留了 shadcn/ui 代码属于你 的核心哲学。迁移后如何按区块整体升级页面除了单个组件SmoothUI 还提供了完整的页面区块适合将整页从基础版升级为动效版。这些区块分类存放在 packages/smoothui/blocks/ 目录下包括 导航头部Header 系列header-1 到 header-6✨ 功能特性Features 系列features-1 至 features-3 定价方案Pricing 系列pricing-1 至 pricing-3 客户评价Testimonials 系列 数据统计Stats 系列# 直接安装整个区块 npx smoothui-clilatest add hero npx smoothui-clilatest add pricing-1 testimonials-2区块组件同样采用 shadcn/ui 的组合式写法迁移时只需替换对应区域的 JSX样式变量CSS Variables与主题体系完全兼容。常见迁移问题与快速解决技巧1. 出现 Cannot find module /lib/utils/cn 报错检查tsconfig.json中是否配置了路径别名{ compilerOptions: { paths: { /*: [./src/*] } } }2. 缺少 clsx 或 tailwind-merge 依赖SmoothUI CLI 会自动安装但手动复制组件时请补上pnpm add clsx tailwind-merge motion lucide-react3. 与已有 shadcn/ui 组件命名冲突无需担心SmoothUI 组件默认安装在components/smoothui/ui/子目录下与原有组件完全隔离按需导入即可。4. 想要批量查看可选组件npx smoothui-clilatest list更多疑难解答可参考 README 的 Troubleshooting 章节或直接阅读项目源码packages/smoothui/ 目录结构清晰每个组件自带__tests__测试与元信息。总结平滑迁移的三步走从 shadcn/ui 平滑迁移到 SmoothUI本质上是一次能力叠加而非推倒重来准备确认 React 19 Tailwind 4 shadcn/ui 环境就绪安装用npx smoothui-clilatest add 组件名一条命令接入替换对照映射表按需将基础组件升级为动画版本整个过程不需要改动项目框架、样式体系或已有代码真正实现了零成本过渡。如果你追求更精致的交互体验又不想放弃 shadcn/ui 的可控性SmoothUI 就是那个完美的中间答案。【免费下载链接】smoothuiSmoothUI is a collection of beautifully designed components with smooth animations built with React, Tailwind CSS, Shadcn/ui and Motion项目地址: https://gitcode.com/gh_mirrors/sm/smoothui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考