常见问题排查SmoothUI 安装报错的 5 大解决方案【免费下载链接】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/smoothuiSmoothUI 是一个基于 React、Tailwind CSS、Shadcn/ui 和 Motion 打造的高颜值动画组件库一条npx smoothui-cli add命令就能把精美组件装进项目。但很多新手在安装 SmoothUI 时总会遇到各种报错本文整理了 5 个最常见的 SmoothUI 安装报错场景并给出一步步的解决方案帮你快速扫清障碍、顺利跑起来。 报错一认证错误 401Unauthorized报错现象执行npx shadcnlatest add smoothui/siri-orb时终端提示You are not authorized to access the item。原因分析这通常发生在你使用了 Vercel 预览Preview部署地址作为 registry 来源时预览环境带有访问鉴权导致组件清单拉取失败。解决方案把components.json里的 registry 地址改为生产环境地址即可{ registries: { smoothui: https://smoothui.dev/r/{name}.json } }如果不想手动配置也可以直接用官方 CLI 安装它会自动指向正确的 registry 源npx smoothui-cli add siri-orb 报错二Registry 未找到404报错现象提示The item at https://smoothui.dev/r/registry.json was not found或者提示Component xxx not found。原因分析组件名拼写错误、registry 源不可达或使用了搜索类命令但该接口不支持都会触发 404。解决方案先在官方组件列表里确认组件名拼写例如siri-orb、rich-popover、animated-input注意大小写与连字符。不要依赖搜索命令直接指定组件名安装npx shadcnlatest add smoothui/siri-orb使用 smoothui-cli list 命令查看当前可用的全部组件确认名称无误。 报错三找不到模块/lib/utils/cn报错现象安装完成后编译报错Cannot find module /lib/utils/cn或类似的/components/...找不到模块。原因分析SmoothUI 组件内部使用/*路径别名引入公共工具和兄弟组件而你的项目没有在tsconfig.json中配置对应的 paths 别名。CLI 的路径检测逻辑见 scripts/utils/detect.ts它默认会尝试读取 tsconfig 中的别名。解决方案在项目根目录的tsconfig.json中补充路径别名根据你的实际目录结构调整{ compilerOptions: { baseUrl: ., paths: { /*: [./src/*] } } }如果项目目录结构不同例如src换成了app把./src/*改成对应的实际路径即可。 报错四缺少依赖clsx/tailwind-merge/motion报错现象编译或运行时提示Cannot find module clsx、Cannot find module motion等。原因分析部分组件依赖clsx、tailwind-merge、motion等第三方包。CLI 会自动安装依赖但如果使用了手动复制源码的安装方式或依赖安装中途失败就会出现缺失。解决方案手动补齐缺失的依赖pnpm add clsx tailwind-merge motion lucide-react不同包管理器对应命令如下包管理器命令npmnpm install clsx tailwind-merge motion lucide-reactpnpmpnpm add clsx tailwind-merge motion lucide-reactyarnyarn add clsx tailwind-merge motion lucide-reactbunbun add clsx tailwind-merge motion lucide-react同时确认项目根目录存在lib/utils/cn.ts工具文件组件依赖它做 className 合并内容参考 README.md 中的手动安装章节import { clsx, type ClassValue } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }⚙️ 报错五Node 版本过低或包管理器识别错误报错现象运行npx smoothui-cli add时直接报 Node 语法错误或终端提示 Detected: components/ui/ (npm)但项目实际用的是 pnpm。原因分析SmoothUI CLI 要求Node.js 18 及以上见 package.json 中的 engines 字段同时 CLI 会通过项目中的锁文件自动识别包管理器pnpm-lock.yaml、yarn.lock、bun.lockb等如果你的项目没有锁文件就会默认回退到 npm。解决方案检查 Node 版本node -v低于 18 请升级到 LTS 版本推荐 20。确保项目提交了锁文件如pnpm-lock.yaml这样 CLI 才能正确识别包管理器。也可以在package.json中显式声明{ packageManager: pnpm11.1.2 } 总结安装 SmoothUI 的推荐姿势避开上面 5 个坑最省心的安装流程是使用 Node.js 18推荐 20 LTS用官方 CLI 一条命令安装npx smoothui-cli add 组件名确保tsconfig.json配置了/*路径别名保持锁文件在仓库中方便 CLI 识别包管理器若手动安装务必补齐clsx、tailwind-merge、motion等依赖如果以上方案仍无法解决你的 SmoothUI 安装报错可以查看项目的 CONTRIBUTING.md 和 CLAUDE.md 了解开发与协作细节或在社区里描述完整的报错信息含命令、Node 版本和项目结构通常很快就能定位问题。祝你顺利装好组件用流畅的动画点亮你的页面✨【免费下载链接】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），仅供参考
常见问题排查：SmoothUI 安装报错的 5 大解决方案
常见问题排查SmoothUI 安装报错的 5 大解决方案【免费下载链接】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/smoothuiSmoothUI 是一个基于 React、Tailwind CSS、Shadcn/ui 和 Motion 打造的高颜值动画组件库一条npx smoothui-cli add命令就能把精美组件装进项目。但很多新手在安装 SmoothUI 时总会遇到各种报错本文整理了 5 个最常见的 SmoothUI 安装报错场景并给出一步步的解决方案帮你快速扫清障碍、顺利跑起来。 报错一认证错误 401Unauthorized报错现象执行npx shadcnlatest add smoothui/siri-orb时终端提示You are not authorized to access the item。原因分析这通常发生在你使用了 Vercel 预览Preview部署地址作为 registry 来源时预览环境带有访问鉴权导致组件清单拉取失败。解决方案把components.json里的 registry 地址改为生产环境地址即可{ registries: { smoothui: https://smoothui.dev/r/{name}.json } }如果不想手动配置也可以直接用官方 CLI 安装它会自动指向正确的 registry 源npx smoothui-cli add siri-orb 报错二Registry 未找到404报错现象提示The item at https://smoothui.dev/r/registry.json was not found或者提示Component xxx not found。原因分析组件名拼写错误、registry 源不可达或使用了搜索类命令但该接口不支持都会触发 404。解决方案先在官方组件列表里确认组件名拼写例如siri-orb、rich-popover、animated-input注意大小写与连字符。不要依赖搜索命令直接指定组件名安装npx shadcnlatest add smoothui/siri-orb使用 smoothui-cli list 命令查看当前可用的全部组件确认名称无误。 报错三找不到模块/lib/utils/cn报错现象安装完成后编译报错Cannot find module /lib/utils/cn或类似的/components/...找不到模块。原因分析SmoothUI 组件内部使用/*路径别名引入公共工具和兄弟组件而你的项目没有在tsconfig.json中配置对应的 paths 别名。CLI 的路径检测逻辑见 scripts/utils/detect.ts它默认会尝试读取 tsconfig 中的别名。解决方案在项目根目录的tsconfig.json中补充路径别名根据你的实际目录结构调整{ compilerOptions: { baseUrl: ., paths: { /*: [./src/*] } } }如果项目目录结构不同例如src换成了app把./src/*改成对应的实际路径即可。 报错四缺少依赖clsx/tailwind-merge/motion报错现象编译或运行时提示Cannot find module clsx、Cannot find module motion等。原因分析部分组件依赖clsx、tailwind-merge、motion等第三方包。CLI 会自动安装依赖但如果使用了手动复制源码的安装方式或依赖安装中途失败就会出现缺失。解决方案手动补齐缺失的依赖pnpm add clsx tailwind-merge motion lucide-react不同包管理器对应命令如下包管理器命令npmnpm install clsx tailwind-merge motion lucide-reactpnpmpnpm add clsx tailwind-merge motion lucide-reactyarnyarn add clsx tailwind-merge motion lucide-reactbunbun add clsx tailwind-merge motion lucide-react同时确认项目根目录存在lib/utils/cn.ts工具文件组件依赖它做 className 合并内容参考 README.md 中的手动安装章节import { clsx, type ClassValue } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }⚙️ 报错五Node 版本过低或包管理器识别错误报错现象运行npx smoothui-cli add时直接报 Node 语法错误或终端提示 Detected: components/ui/ (npm)但项目实际用的是 pnpm。原因分析SmoothUI CLI 要求Node.js 18 及以上见 package.json 中的 engines 字段同时 CLI 会通过项目中的锁文件自动识别包管理器pnpm-lock.yaml、yarn.lock、bun.lockb等如果你的项目没有锁文件就会默认回退到 npm。解决方案检查 Node 版本node -v低于 18 请升级到 LTS 版本推荐 20。确保项目提交了锁文件如pnpm-lock.yaml这样 CLI 才能正确识别包管理器。也可以在package.json中显式声明{ packageManager: pnpm11.1.2 } 总结安装 SmoothUI 的推荐姿势避开上面 5 个坑最省心的安装流程是使用 Node.js 18推荐 20 LTS用官方 CLI 一条命令安装npx smoothui-cli add 组件名确保tsconfig.json配置了/*路径别名保持锁文件在仓库中方便 CLI 识别包管理器若手动安装务必补齐clsx、tailwind-merge、motion等依赖如果以上方案仍无法解决你的 SmoothUI 安装报错可以查看项目的 CONTRIBUTING.md 和 CLAUDE.md 了解开发与协作细节或在社区里描述完整的报错信息含命令、Node 版本和项目结构通常很快就能定位问题。祝你顺利装好组件用流畅的动画点亮你的页面✨【免费下载链接】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），仅供参考