panda-css-migrate

Panda CSS v1 → v2

v2 保留了作者 API，并使用 Rust 重写了编译器。你的 panda.config.ts 可以沿用。大多数问题出在配置连接、少数 CLI 标志，以及不再存在的包上。

完整指南见升级到 v2。本指南将带你按顺序完成升级。以下任何步骤需要更多细节时，请阅读完整指南。

开始之前

检查项目是否能够运行 v2：

• 仅支持 ESM。 不提供 CommonJS 构建。项目需要设置 "type": "module"、使用 .mjs 文件，或使用支持 ESM 的打包器。 require('@pandacss/dev') 将无法运行。
• Node 22 或更高版本。 已发布的包声明了 "engines": { "node": ">=22" }。

如果任一条件不满足，请先修复。在配置加载之前，其他事情都不重要。

升级清单

按顺序操作。每完成一组后运行 panda build；如果一次批量处理，失败问题会叠加。

1. 将所有 @pandacss/* 包一起升级到 v2。

pnpm add -D @pandacss/dev@latest
pnpm add -D @pandacss/postcss@latest   # or @pandacss/vite, @pandacss/webpack, @pandacss/rollup

切勿混用 v1 和 v2 包。所有包都使用同一版本。

2. 移除对不再存在的包的导入。 这些包的功能已迁移到 @pandacss/compiler：@pandacss/core、 @pandacss/extractor、@pandacss/generator、@pandacss/node、@pandacss/parser、@pandacss/token-dictionary、 @pandacss/is-valid-prop、@pandacss/logger、@pandacss/reporter 和 @pandacss/studio。如果项目只使用 @pandacss/dev 加上一个打包器插件，则无需操作。

3. 显式添加预设。 v2 不会自动注入预设。没有预设的配置会得到一个基础系统：没有 bg 或 color 工具类、没有间距或字体比例，也没有 _hover。

export default defineConfig({
  presets: ['@pandacss/preset-base', '@pandacss/preset-panda'],
})

这是“升级后所有东西都坏了”最常见的原因。

4. 将钩子移至插件。

// ❌ v1
hooks: { 'parser:before': handler }

// ✅ v2
plugins: [{ name: 'local', hooks: { 'parser:before': { filter: { id: '**/*.{jsx,tsx}' }, handler } } }]

支持的钩子：config:resolved、preset:resolved、parser:before、codegen:prepare、codegen:done、cssgen:done。

已移除的钩子：context:created、parser:after、config:change、tokens:created、utility:created 和 parser:before.configure(...)。现在 cssgen:done 只能用于观察，因此无法重写 CSS 字符串。

如果你曾使用 cssgen:done 删除未使用的令牌或关键帧，请改用 optimize：

optimize: {
  removeUnusedTokens: true,
  removeUnusedKeyframes: true,
  smartCompoundVariants: true,
}

5. 拆分 createStyleContext。 它已从 <outdir>/jsx 中移除。

• 配方配置（cva）→ createRecipeContext → { withContext }
• 插槽配方（sva）→ createSlotRecipeContext → { withRootProvider, withProvider, withContext }

6. 将模板字面量样式转换为对象。 syntax 选项、--syntax 初始化标志和标签模板样式均已移除。

// ❌ v1
const Button = styled.button`
  padding: 10px 15px;
`

// ✅ v2
const Button = styled('button', { base: { padding: '10px 15px' } })

之后运行 panda codegen --clean，以便重新生成旧运行时。

7. 替换 globalPositionTry。 使用 theme.positionTry 和 positionTry() 工厂函数。

// ✅ v2
theme: {
  positionTry: {
    bottom: {
      top: 'anchor(bottom)'
    }
  }
}
css({ positionTryFallbacks: positionTry('bottom') })

8. 修复 scrollbarWidth。 现在它接受 auto | thin | none，而不是 sizes 令牌。scrollbarWidth: '4' 一直都是无效的 CSS。scrollbarColor 中的单个颜色令牌应改用 scrollbarThumb。

9. 更新 CLI 用法。

• panda inspect、panda validate、panda info → panda doctor（在脚本中添加 --json）
• panda ship → panda lib，使用方在配置中设置 designSystem
• panda mcp / panda init-mcp → npx -y @pandacss/mcp
• --cpu-prof → --profile（写入 .panda/trace.json 和 .panda/timings.json）
• --silent / --quiet / --verbose → --log-level silent|error|warn|info|debug
• 共享标志使用 kebab-case：--max-warnings、--watch-debounce、--trace-output、--trace-file

10. 重新连接设计系统。 如果项目曾使用 panda ship 发布或使用某个库：

// consumer config
export default defineConfig({ designSystem: '@acme/design-system' })

切勿将构建信息放入 include。运行 panda build 后，从本地 outdir 导入样式。

11. 运行构建并查看诊断信息。 运行 panda build，然后运行 panda doctor。如果发现异常，<outdir>/debug 下的 panda debug 转储会准确显示新引擎提取的内容。

如果 CSS 发生变化

v2 的目标是与 v1 保持一致。以下差异是有意为之，请在提交 bug 前先检查：

• 边框和简写覆盖。 原子规则按属性覆盖范围排序，而不是按源顺序排序。现在，全边简写会覆盖单边设置。若要让覆盖生效，请使用长属性：borderInlineEndWidth: '0'，而不是 borderInlineEnd: '0'。
• 复合变体会即时以命名类的形式输出到 @layer recipes.compound_variants。设置 optimize.smartCompoundVariants: true，即可只输出实际使用的组合。
• 不再重置通用变量。 v1 会在每个元素上设置 --translate-x、--blur 等变量。v2 使用 @property 注册这些变量。如果目标引擎不支持 @property，请设置 optimize.propertyFallback: true。
• 断点使用范围语法，例如 @media (width >= 48rem)。px 和 em 会规范化为 rem。
• 带前缀的声明会排在前面（-webkit-mask-image 在 mask-image 之前）。
• 未使用的 @property 注册会被移除。 如果读取某个已注册变量的 CSS 只有 Panda 不会扫描的内容，请也在 globalCss 中声明该变量。
• 具有相同声明的相邻规则会合并，共用 @media 或 @supports 封装器的规则也会归组。

部分位置的类名已变更（例如排版简写）。不要对生成的类名进行断言。

只是变动，并非损坏

如果升级后出现以下情况，并不代表是你引入了回归：

• 基于 Astro 的 Studio 已移除。计划推出由 CLI 生成的替代方案。
• 部分社区预设（preset-atlaskit、preset-open-props）和独立插件尚未移植。请使用一方的 @pandacss/preset-typography，而不是社区排版预设。它的默认尺寸是 md，而不是 base。
• 如果使用 @pandacss/postcss 时构建异常，请先尝试 Vite 插件或直接运行 panda build 进行排查，再提交 bug。

以下情况表示运行正常

• panda build 在无需重写的配置上完成运行，且没有诊断信息。
• 已显式设置 presets，且 bg 等工具类和 _hover 等条件重新正常解析。
• 没有任何内容导入 @pandacss/core、@pandacss/node 或其他已合并的软件包。
• 配置根级别没有 hooks 键，也没有残留 createStyleContext 调用。
• 与 v1 的 CSS 差异仅包含上述有意为之的差异。

另请参阅

• 完整指南：升级到 v2。
• 升级完成后编写样式：调用 Skill 工具并输入“panda-css”。
• Tokens 和配方架构：调用 Skill 工具并输入“panda-css-theming”。