深度配置shadcn/lintsettings识别选项与组件导入匹配完全指南【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lintshadcn/lint是一个面向 AI 编码代理的 Tailwind 设计系统检查器而settings.shadcn 配置是让它正确识别你的设计系统的关键。本文将带你完整掌握六大识别选项ui、componentImports、ignoreImports、mergeFunctions、variantFunctions、note与组件导入匹配机制帮助你快速完成深度配置。为什么需要配置识别shadcn/lint的规则如no-restyle、no-raw-colors都建立在同一个前提上先认出哪个 import 是设计系统组件。识别逻辑在 packages/lint/src/project/component-imports.ts 中实现。两类项目的识别方式不同项目类型识别方式shadcn/ui 项目自动读取components.json的aliases.ui零配置自定义项目如组件放在/ds必须通过settings.shadcn显式声明 注意你不需要使用 shadcn/ui。只要组件放在自定义目录、使用自己的主题shadcn/lint同样完全可用。六大识别选项完全解析在 ESLint 或.oxlintrc.json中把settings写在包含规则的配置对象根部按需只写你需要的项settings: { shadcn: { ui: /ds, componentImports: [^acme/ui(/|$)], ignoreImports: [^acme/ui/internal(/|$)], mergeFunctions: [customMerge], variantFunctions: [variants], note: See DESIGN.md for design rules and approved exceptions., }, }各选项的完整实现在 packages/lint/src/rules/settings.ts官方说明见 docs/README.md 的 Settings 章节。1. ui前缀匹配一行搞定最常用场景ui是字面前缀而非正则。/ds会匹配/ds和/ds/button但不会匹配/dsx按整段边界匹配。支持字符串或字符串数组。它的本质是被自动转换成正则追加到componentImports中源码中^${escapeRegExp(prefix)}(/|$)的生成逻辑见 settings.ts 第 42–50 行。因此ui前缀始终与componentImports叠加生效而不是二选一。2. componentImports正则匹配覆盖额外目录或包当你的组件散落在多个位置多个目录、多个 npm 包时用正则精确圈定componentImports: [^/ds(/|$), ^acme/ui(/|$)]所有识别选项均接受字符串或字符串数组两种写法。3. ignoreImports排除优先先于一切识别ignoreImports匹配的 import 会跳过组件识别且优先级高于ui与componentImports。典型用途排除内部工具包、避免对第三方包误报。ignoreImports: [^acme/ui/internal(/|$)]4. mergeFunctions 与 variantFunctions扩展可读取的函数检查器需要理解代码里哪些函数调用包含 class 值。内置函数为类参函数cn、cx、clsx、cva、tv、twMerge、twJoin、classNames变体对象函数cva、tv你的自定义函数如mergeClasses、variants通过这两个选项追加到内置列表中。配置后调用如mergeClasses(mt-4, w-full)内部的 class 也能被检查。5. note给每条诊断追加全局备注note只接受字符串文本会被追加到每条规则的错误/警告末尾包括自定义 message适合引导代理去查设计规范文档。规则级选项优先于全局 settings一个容易踩的优先级细节场景生效结果规则自身配置了componentImports规则自己的值生效覆盖全局 settings全局设置了ui前缀前缀仍会追加到规则的匹配中类型写错如ui: 42警告一次后忽略该值不会崩溃也就是说全局 settings 提供默认值规则选项提供覆盖能力而ui前缀是唯一永远叠加的项。测试用例可参考 packages/lint/test/settings.test.ts。Monorepo 中的组件导入匹配共享 UI 包如packages/ui场景下用工作区的导入前缀配置ui{ settings: { shadcn: { ui: workspace/ui/components } }, rules: { shadcn/no-restyle: [error, { allow: [layout] }] }, overrides: [ { files: [packages/ui/src/components/**], rules: { shadcn/no-restyle: off } } ] }两个要点组件目录内关闭no-restyle组件要能样式化自己override 必不可少若各 app 的components.json已指向共享 UI 包可省略settings.shadcn.uilinter 会走 TypeScript paths 和包 exports 解析见 docs/how-it-works.md。三个高频坑位自查⚠️改了组件目录后记得同步 override如从components/ui/**换到src/ds/**override 的文件模式要一起改否则组件目录内的样式检查会误报⚠️识别选项不影响no-inline-styles该规则只作用于 CSS 属性名ui/componentImports等对其无效只有note对它生效⚠️别名无法解析会警告一次当ui别名找不到目录时linter 会提示识别不到设计系统组件此时应修正aliases.ui或补上componentImports——静默地不识别是它明确反对的失败模式。参考与延伸阅读官方文档入口docs/README.md规则共享选项识别、allow/deny、contractsdocs/rules.md组件识别与主题解析原理docs/how-it-works.mdsettings 合并逻辑源码packages/lint/src/rules/settings.ts配好识别之后你的每一条no-restyle报错都会带上来自你自己设计系统的修复建议——这正是shadcn/lint代理优先理念的核心价值。【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考