Panda CSS 官方 ESLint 插件实战指南:规则体系、配置方式与源码原理解析

原创2026-10-09 09:12:061,459 阅读
文章标签:前端构建工具开发工具

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 的实现):

  1. 预加载 Panda 项目(配置 + 编译器),保证后续所有规则访问器保持同步执行;
  2. 在 plugins 中以 @pandacss 命名空间注册全部规则;
  3. 按 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 条目做三件事:

  1. 用 categoryOf 判断该属性是否属于 token 类别;
  2. 用 isHardcodedValue 判定值是否为硬编码——实现上会调用 compiler.resolveUtilityValue({ prop, value }) 并排除 CSS 全局关键字(inherit、initial、unset、revert、none、auto、currentcolor、transparent 等,见 src/plugin.ts)以及解析结果为 var(...) 的情况,结果会按 prop\0value 键做内存缓存;
  3. 用 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 一致):

  1. settings.panda.configPath
  2. settings['@pandacss/configPath'](迁移别名)
  3. 被 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 场景中按项目粒度组织配置,本文介绍的规则与源码路径都能作为你深入使用和二次开发的起点。

登录后查看全文
panda