Panda CSS 官方 ESLint 插件实战指南:规则体系、配置方式与源码原理解析
Panda CSS 官方 ESLint 插件实战指南:规则体系、配置方式与源码原理解析
@pandacss/eslint-plugin 是 Panda CSS 官方推出的 ESLint 插件,它不依赖任何预生成的 JSON 配置文件,而是直接读取项目中的 panda.config.ts,用与构建完全一致的编译器去理解每一个文件的含义,从而捕获拼写错误的 token、已被废弃的 recipe、以及本应使用设计 token 的硬编码颜色。本文以该包 CHANGELOG.md 的版本演进为主线,结合 README.md 与插件源码(src/plugin.ts、src/configs.ts、src/core/linter.ts 等),完整讲解插件的安装配置、全部规则与选项、oxlint 支持方式,以及底层"一次加载配置、同步执行规则"的架构设计。读完你将能独立接入并调优 Panda 的 lint 能力,并理解它与 v2 Rust 引擎(基于 Oxc)之间的关系。
一、插件定位:lint 与构建共享同一套编译结果
传统 CSS-in-JS 的 lint 插件往往基于独立的 AST 遍历规则去猜测代码意图,很容易与真实构建行为脱节。@pandacss/eslint-plugin 的设计核心恰好相反:规则运行在真实编译器之上。
根据 README.md 与 src/core/linter.ts 的实现,插件会在启动阶段基于 panda.config.ts 构建一个 Panda Project(配置加载 + 编译器初始化),随后每 lint 一个文件,就调用编译器对该文件做一次完整解析——哪些调用是 css()、哪个标签是 recipe、某个值最终解析到了哪颗 token——规则只是把这些编译结果翻译成 ESLint 的 report 与 fix。用官方变更日志(2.0.0 版本)的原话来说,这个插件"lints against the same extraction your build uses",即 lint 与构建共享同一套提取与解析逻辑。
在 Panda 2.0 中,底层编译器已被替换为基于 Oxc 的 Rust 引擎(见 CHANGELOG.md 的 2.0.0 Major Changes 条目),构建过程中不再依赖 ts-morph 或 PostCSS。插件因此获得了更快的单文件解析能力,也为后续的 extraction-diagnostics 规则(直接汇报编译器在文件中遇到的解析与提取问题)提供了基础。
二、安装与快速接入(ESLint v9 flat config)
插件当前处于 Beta 阶段,仅支持 ESLint v9 的 flat config,且需要 Node 22 或更高版本(package.json 中 peerDependencies 为 eslint >=9,engines 为 node >=22)。
pnpm add -D @pandacss/eslint-plugin
2.1 推荐配置:一条配置搞定
因为加载 Panda 配置是异步操作,而 ESLint 的 flat config 支持解析为 Promise 的配置对象,所以可以在 eslint.config.mjs 中直接 await:
import panda from '@pandacss/eslint-plugin'
export default [await panda.configs.recommended({ configPath: './panda.config.ts' })]
这段配置会做三件事(对应 src/configs.ts 的实现):
- 预加载 Panda 项目(配置 + 编译器),保证后续所有规则访问器保持同步执行;
- 在
plugins中以@pandacss命名空间注册全部规则; - 按
RECOMMENDED_RULES表开启推荐规则并设定默认严重级别。
recommended 默认只作用于 JS/TS/JSX 源文件(glob 为 **/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}),且不设置 parser——请沿用项目已有的 parser 配置(TS 项目通常是 typescript-eslint,框架项目则来自其 ESLint preset)。因为 Panda 规则直接读取源码文本,任何能产出 Program 的 parser 都可以工作。
如果你想 lint .vue、.svelte、.astro 等框架文件,需要在配置好对应 parser 之后通过 files 显式纳入:
await panda.configs.recommended({
configPath: './panda.config.ts',
files: ['**/*.{ts,tsx,vue}'],
})
2.2 CommonJS 下的写法
在 eslint.config.cjs 中,导出 Promise 即可,ESLint 会自行 resolve:
module.exports = (async () => {
const panda = (await import('@pandacss/eslint-plugin')).default
return [await panda.configs.recommended({ configPath: './panda.config.ts' })]
})()
顶层 await 在 eslint.config.mjs(或带 "type": "module" 的 .js)以及 jiti ≥ 2 / Node ≥ 22.13 的 eslint.config.ts、Deno、Bun 环境中均可直接使用。
三、全部规则全景:推荐规则与可选规则
3.1 recommended 默认开启的规则
src/configs.ts 中的 RECOMMENDED_RULES 表定义如下:
| 规则 | 默认级别 | 作用 |
|---|---|---|
no-invalid-token-paths |
error | 引用不存在的 token,例如 token('colors.ghost') |
no-invalid-nesting |
error | 嵌套选择器缺少 & 前缀(写了 ':hover' 而不是 '&:hover'),Panda 会静默忽略这类样式;规则会建议补上 & |
file-not-included |
error | 文件使用了 Panda 但位于 config 的 include 之外,样式永远不会被生成 |
no-deprecated |
warn | 使用了被废弃的 token、utility、recipe 或 pattern |
prefer-token |
warn | 在存在 token 的地方使用了原始值,并给出应使用的 token;recommended 中默认限定在 colors 类别(即 v1 的 no-hardcoded-color) |
no-debug |
warn | 残留的 debug: true |
extraction-diagnostics |
warn | 编译器在该文件中遇到的解析或提取问题 |
该表被 tests/configs.test.ts 逐项断言,测试创建了一个含 red.500 token 的最小 Panda 项目,验证返回的 flat config 中规则 id 前缀为 @pandacss/、严重级别与上表一致、settings.panda.configPath 被正确写入。
3.2 需要手动开启的规则
以下规则默认关闭,按项目需求单独开启:
| 规则 | 作用 |
|---|---|
no-important |
样式中的 !important |
no-margin-properties |
margin 相关属性,引导改用 gap 与布局模式 |
no-physical-properties |
有逻辑属性对应物的物理属性(如 left → insetInlineStart) |
no-shorthand-longhand-mix |
同一块中同时出现 shorthand 与它自己的 longhand(如 margin + marginLeft)。无论书写顺序如何,longhand 最终都会胜出,因此这种行为应当被标记。支持 ignore 选项 |
consistent-property-style |
统一属性书写风格:Panda 的 shorthand 别名(ml)或 longhand 规范名(marginLeft)。可自动修复(autofix),接受 style: 'shorthand' | 'longhand'(默认 longhand)与 ignore |
prefer-text-style |
一个样式对象设置了两个及以上排版属性,本应合并为一个 textStyle token |
no-primitive-token |
在已有对应语义 token 的类别中使用了原始/基础 token(primitive token)。接受 categories 与 allow |
no-descendant-selectors |
标记那些样式到其他元素的选择器(如 & > li、.foo &),让每个样式都只作用于自身元素;跨元素状态仍可通过 _groupHover 等条件实现。该规则于 2.0.0-beta.16 新增 |
开启方式与普通 ESLint 规则无异:
import panda from '@pandacss/eslint-plugin'
export default [
await panda.configs.recommended({ configPath: './panda.config.ts' }),
{ rules: { '@pandacss/no-important': 'error' } },
]
在 src/plugin.ts 的 bindRules 中可以看到全部 14 个规则的注册逻辑:no-important、no-descendant-selectors、no-margin-properties、no-physical-properties、no-shorthand-longhand-mix、consistent-property-style、prefer-text-style 等都属于"opt-in 的样式/强制类规则",不在 recommended 中;注释也明确说明 recommended 会把 prefer-token 限定在 colors(替代旧的 no-hardcoded-color)。
四、核心规则与选项详解
4.1 prefer-token:把硬编码值映射回设计 token
这是插件最具代表性的规则。它遍历编译器返回的 styleEntries(见 src/rules/prefer-token.ts),对每个 utility 条目做三件事:
- 用
categoryOf判断该属性是否属于 token 类别; - 用
isHardcodedValue判定值是否为硬编码——实现上会调用compiler.resolveUtilityValue({ prop, value })并排除 CSS 全局关键字(inherit、initial、unset、revert、none、auto、currentcolor、transparent等,见 src/plugin.ts)以及解析结果为var(...)的情况,结果会按prop\0value键做内存缓存; - 用
compiler.suggestTokens(prop, value)给出携带该值的候选 token,最多列出 3 个(MAX_LISTED),并以 message 形式逐条给出 editor quick-fix。
诊断信息示例(来自 README.md):
Hardcoded colors value "#f00". Matching tokens: fg.error, red.500.
💡 Use the token "fg.error"
💡 Use the token "red.500"
细节要点:
- 同时展示语义 token 与 primitive token,语义优先;条件性 token(themed)会被标注
(themed)(对应 prefer-token.ts 的label逻辑); - 自动归一化等价形式:
#FFF与#ffffff、16px与1rem会被视为同一值; - 覆盖所有样式书写形态:
css()、style props、响应式数组、按属性的 conditions、以及cva/sva/styled的 recipe 样式(base、variants、compoundVariants); - 逐叶子提供 quick-fix:扁平字面量(
color: '#f00')、嵌套在条件里的值(color: { base: '#f00' })、响应式数组元素(color: ['#f00', ...])都能被单独修复。
选项:
{
rules: {
'@pandacss/prefer-token': ['warn', { categories: ['colors', 'spacing'], allow: ['transparent'] }],
},
}
categories:要强制检查的 token 类别,默认全部;allow:允许保留的原始值白名单。
在 2.1.0 版本中,该规则修复了对 token 值三元表达式以及 flex 等 utility 的误报(false positives),这是变更日志中记录的重要正确性改进。
4.2 no-deprecated:废弃能力巡检
检查废弃 token、utility、recipe 与 pattern,接受 kinds 选项来缩小检查范围:
{ rules: { '@pandacss/no-deprecated': ['warn', { kinds: ['tokens', 'recipes'] }] } }
kinds 合法值为 tokens、utilities、recipes、patterns,默认全部检查。如果你在 config 中为某个 token/recipe 写了 deprecated: 'use X instead',这段作者信息会直接出现在 lint 错误中。
从源码看,废弃信息来自编译器的 spec:bindRules 通过 recipeDeprecations 与 patternDeprecations 两个辅助函数,将 spec 中 recipes、slotRecipes、patterns 里的 deprecated 字段汇总成 名称 → 弃用信息 的映射(src/plugin.ts),再交给规则使用。
4.3 no-primitive-token:从基础 token 走向语义 token
该规则于 2.0.0-beta.9 加入(变更日志:"Add no-primitive-token (and inspection metadata) so you can require semantic tokens when a matching category exists")。它与 prefer-token 互补:prefer-token 把硬编码 CSS 值映射到 token,no-primitive-token 把 primitive token 映射到语义 token。
{ rules: { '@pandacss/no-primitive-token': ['error', { categories: ['colors'], allow: ['red.500'] }] } }
categories:要强制的类别,默认是"存在语义 token 的类别";allow:允许保留的 primitive token 路径白名单。
没有语义 token 的类别会被自动跳过,例如你没定义语义化 spacing token,那么 spacing 的 primitive 值就是允许的。
4.4 从 v1 的 no-hardcoded-color 迁移
v1 时代的 no-hardcoded-color 在 v2 中就是"限定在 colors 类别的 prefer-token"。迁移方式:
{ rules: { '@pandacss/prefer-token': ['warn', { categories: ['colors'] }] } }
使用 configs.recommended 的项目无需任何改动,因为推荐配置已经默认如此。
4.5 no-invalid-nesting:把静默错误变成显式报错
Panda 会静默忽略缺少 & 前缀的嵌套选择器(':hover'),这让开发者很难察觉样式根本没生效。该规则把这类写法标记出来并建议补上 &。由于它在 recommended 中是 error 级别,能有效阻止"写了但没生效"的样式进入代码库。
五、多包仓库(Monorepo)配置
每个 Panda 配置调用一次 recommended,再用 files 把规则限定到对应包:
export default [
{
...(await panda.configs.recommended({ configPath: './packages/web/panda.config.ts' })),
files: ['packages/web/**'],
},
{
...(await panda.configs.recommended({ configPath: './packages/app/panda.config.ts' })),
files: ['packages/app/**'],
},
]
注意一个已知限制(README 中有明确说明):Panda 配置只会加载并缓存一次。长时间运行的编辑器会话不会感知 panda.config 的修改,需要重启 ESLint 才能生效。
六、配置查找顺序与 Settings
插件查找 Panda 配置的顺序(README.md 与 src/core/settings.ts 一致):
settings.panda.configPathsettings['@pandacss/configPath'](迁移别名)- 被 lint 文件最近的 Panda 配置(就近自动发现)
示例:
export default [panda.configs.recommended(), { settings: { panda: { configPath: './panda.config.ts' } } }]
resolvePandaSettings 同时支持 cwd 与 strictDiagnostics 字段:cwd 缺省时回落到 context 的 cwd,再回落 process.cwd()。
七、oxlint 支持:同一套规则、另一个运行时
从 2.0.0-beta.4 起,插件的规则就同时能在 oxlint 下运行。oxlint 支持 ESLint 兼容的 JS 插件,因此只需把 jsPlugins 指向 @pandacss/eslint-plugin/oxlint 入口:
{
"jsPlugins": ["@pandacss/eslint-plugin/oxlint"],
"rules": {
"@pandacss/no-invalid-nesting": "error",
"@pandacss/no-debug": "warn",
"@pandacss/prefer-token": ["warn", { "categories": ["colors"] }]
}
}
该入口(src/oxlint.ts)会从工作目录自动发现 panda.config.*;如果配置位于非标准位置,可以通过 PANDA_CONFIG_PATH 环境变量指定。由于 oxlint 通过动态 import 加载该模块,文件顶层的 await 会在插件运行前完成项目加载。
单配置限制:与 ESLint flat config 不同(那里可以组合多个 recommended({ configPath }) 条目),oxlint 一次只加载一个 JS 插件、绑定一个 Panda 项目。对于自定义路径或多个配置的 monorepo,推荐写一个本地小插件,把 configPath 写死:
// oxlint-panda.mjs
import { createPandaPlugin } from '@pandacss/eslint-plugin'
const { rules } = await createPandaPlugin({ configPath: './panda.config.ts' })
export default { meta: { name: '@pandacss' }, rules }
{ "jsPlugins": ["./oxlint-panda.mjs"], "rules": { "@pandacss/no-invalid-nesting": "error" } }
oxlint.config.ts(通过 defineConfig,Node ≥ 22.18)的使用方式相同——插件仍按路径引用。
八、源码架构:一次预加载、全程同步执行
插件在性能设计上的关键决策是:每个配置只构建一个编译器,跨文件复用;规则访问器始终同步。这一设计最早出现在 2.0.0-beta.4 的变更日志中("Config and compiler loading is preloaded once per project so rule visitors stay synchronous")。
具体分层如下:
- src/core/settings.ts:将 ESLint context 的
settings解析为规范化配置(configPath/cwd/strictDiagnostics)。 - src/core/project-cache.ts:以
cwd + configPath为键(projectCacheKey)缓存Promise<Project>,同一个 Panda 项目只构建一次;默认通过createProjectFromConfig从@pandacss/compiler/tooling创建。 - src/core/linter.ts:
Linter类把"取项目 → 取文件源码 → 调用 Inspector 检查"编排起来,产出包含FileInspectionResult的LintInspection。 - src/core/inspector.ts:对单个文件调用编译器完成检查,并按源码范围做索引,供规则在正确的 ESLint location 上报。
- src/plugin.ts:
bindRules把规则绑定到已加载的项目——构建SpecIndex(用于"属性 → token 类别"解析)、生成硬编码值分类器、包装suggestTokens/suggestSemanticTokens等编译器查询能力,然后实例化全部 14 条规则。 - src/configs.ts:
recommended()是异步入口,负责预加载项目、绑定规则、组装 flat config 并写入推荐级别。
因此每条规则拿到的不是"它自己重新解析的 AST 结论",而是编译器对这个文件已经完成的一次解析结果,规则只做翻译与上报——这也是规则 visitor 能保持同步、整体性能可控的根本原因。
九、版本演进时间线(对应 CHANGELOG 主线)
结合 packages/eslint-plugin/CHANGELOG.md,插件能力的演进脉络清晰可见:
| 版本 | 关键变化 |
|---|---|
| 2.0.0-beta.4 | 插件核心诞生:settings 解析、项目缓存、检查缓存、源码范围查找;首批 7 条规则(extraction-diagnostics、file-not-included、no-invalid-token-paths、no-debug、no-deprecated、prefer-token、no-shorthand-longhand-mix、consistent-property-style、no-invalid-nesting);configs.recommended({ configPath }) 入口;规则同步执行;oxlint 兼容入口 |
| 2.0.0-beta.9 | 新增 no-primitive-token 及配套的 inspection metadata |
| 2.0.0-beta.16 | 新增可选规则 no-descendant-selectors |
| 2.0.0 | 随 Panda 2.0 发布,底层编译引擎切换为基于 Oxc 的 Rust 引擎;插件"lint against the same extraction your build uses" |
| 2.1.0 | 修复 prefer-token 对 token 值三元表达式与 flex 等 utility 的误报;extraction-diagnostics 开始上报未知条件(unknown condition)警告(ESLint 与 oxlint 同步) |
| 2.1.1 / 2.1.2 | 跟随 @pandacss/compiler、@pandacss/config、@pandacss/compiler-shared 的依赖更新 |
包当前版本为 2.1.2(见 package.json),exports 提供 ./oxlint 子路径,构建脚本通过 tsup 将 src/index.ts 与 src/oxlint.ts 打包为 ESM 并生成类型声明。
十、已知限制与使用注意
- Beta 阶段:README 明确标注 Beta,且绝大多数规则为 report-only,只有少数规则提供修复/建议。
- 只支持 ESLint v9 flat config;v8 及 eslintrc 格式不在支持范围内。
- 配置缓存:
panda.config修改后需重启 ESLint 才能生效(编辑器长会话场景)。 - 框架文件需显式纳入:
.vue/.svelte/.astro依赖各自的 parser 与整体文件范围映射,必须通过files选项启用。 - Node 版本要求:包本身要求 Node ≥ 22;Panda 2.0 整体为 ESM-only。
- oxlint 单项目限制:oxlint 入口每次只绑定一个 Panda 项目,多配置场景请使用本地包装插件。
结语
@pandacss/eslint-plugin 的价值在于把 lint 从"猜测代码意图"提升为"与编译器共享同一份事实"。它直接消费 panda.config.ts 中的 tokens、recipes、patterns 与 utilities,在 ESLint 与 oxlint 两套运行时中提供一致的能力,并借助 Panda 2.0 的 Rust 引擎获得与构建同步的解析结果。无论是通过 configs.recommended 一键接入、按 categories / kinds / style 等选项精细化调优,还是在 monorepo 与 oxlint 场景中按项目粒度组织配置,本文介绍的规则与源码路径都能作为你深入使用和二次开发的起点。