用途：把 Panda CSS 项目从 v1 升级到 v2，或调试在 1.x 正常、2.x 报错的项目。v2 保留编写 API，编译器改用 Rust，panda.config.ts 可沿用，主要破坏点在配置管线、CLI 参数和已移除的包。
前置检查：v2 仅支持 ESM，无 CommonJS 构建，项目需 "type": "module"、.mjs 或支持 ESM 的打包器，require('@pandacss/dev') 不可用；需 Node 22 或更新版本。不满足先修复，否则配置无法加载。
升级步骤（按顺序，每组后运行 panda build）：1) 所有 @pandacss/* 包一起升到 v2，如 pnpm add -D @pandacss/dev@latest 及对应打包器插件，不可混用 v1 与 v2。2) 移除已不存在的包导入，其功能并入 @pandacss/compiler。3) 显式添加 presets，如 presets: ['@pandacss/preset-base', '@pandacss/preset-panda']，否则缺少 bg、color、间距、字体与 _hover。4) 把 hooks 移到 plugins，支持 config:resolved、preset:resolved、parser:before、codegen:prepare、codegen:done、cssgen:done；cssgen:done 改为只读，可用 optimize 的 removeUnusedTokens、removeUnusedKeyframes、smartCompoundVariants 替代。5) 拆分 createStyleContext，recipe 用 createRecipeContext，slot recipe 用 createSlotRecipeContext。6) 模板字符串样式改为对象写法，之后运行 panda codegen --clean。7) 用 theme.positionTry 与 positionTry() 替代 globalPositionTry。8) scrollbarWidth 只接受 auto|thin|none。9) CLI 更新：inspect/validate/info 合并为 panda doctor，ship 改为 lib，mcp 用 npx -y @pandacss/mcp，--cpu-prof 改为 --profile，日志用 --log-level。10) 设计系统改用 designSystem 配置。11) 运行 panda build 与 panda doctor，必要时查看 <outdir>/debug。
CSS 差异：原子规则按属性广度排序，简写可能覆盖单边，需用长写；compound variants 默认急切生成，可开启 smartCompoundVariants；不再有全局变量重置，改用 @property，不支持时设 optimize.propertyFallback；断点用范围语法；未使用的 @property 会被移除；类名有变化，不要断言生成类名。
限制：Astro Studio 已移除，部分社区预设与独立插件未移植，typography 预设默认尺寸为 md。postcss 下异常可改用 Vite 插件或 panda build 排查。资料未提供具体价格与平台信息。