企业官网建设流程全解析

• 前端
• 构建工具
• 开发工具

@pandacss/types是 Panda CSS 全链路类型定义的中枢包，它集中定义了Config、Preset、UserConfig以及贯穿各包的类型面（package.json 与 src/index.ts）。本文以 CHANGELOG.md 为主线，梳理从 2.0.0-beta 系列到 2.1.2 的类型与 API 变更，并对照 packages/types/src 下的源码，讲解firstThatWorks()、keyframes()、positionTry()、viewTransition()等新工厂函数背后的类型契约，以及defineParts移除、Qwik JSX 支持移除等破坏性变更的迁移路径，帮助你在升级或维护类型系统时有的放矢。

版本脉络概览

整体脉络清晰：类型包从"定义静态类型面"逐渐演进为"同时承载新工厂函数（firstThatWorks / keyframes / positionTry / viewTransition）的类型签名、CSS 变量@property注册的类型定义，以及optimize选项的类型描述"。

Panda 2.0 核心变更：类型系统如何支撑 Rust 引擎

2.0.0 的 Major Changes 宣布：Panda 2.0 用基于 Oxc 的 Rust 引擎替换原编译器。用户仍然书写同样的css()、recipes、patterns、tokens 与 JSX props —— 也就是说，类型层保持不变，变化的只是底层实现。CHANGELOG 列出的改进包括：

• 每个文件一次解析、跨文件值解析、原生 CSS 输出，构建中不再需要ts-morph或 PostCSS；
• 提取速度提升 15–37×，watch 模式约 360×，staticCss约 85×；
• 生成的类型更轻，TypeScript 类型实例化数量减少约 99%；
• 运行时css()与 recipes 会记忆化重复样式，最多快约 4×；
• @pandacss/compiler-wasm让同一引擎在浏览器中运行并产出相同 CSS；
• @pandacss/vite、@pandacss/webpack、@pandacss/rollup、@pandacss/bun打包器插件可把 Panda 跑在构建内；
• 开启transform: true后，打包器会把静态的css()、recipe、pattern 与styled()调用重写为类名字符串，样式运行时从 bundle 中消失；
• 通过optimize选择移除未使用的 tokens 与 keyframes、只输出用到的复合变体，并支持对设计系统做 tree-shaking。

这些能力大多被类型化为 config.ts 中的OptimizeOptions、CssgenOptions、CodegenOptions等接口。以OptimizeOptions为例（config.ts），它包含removeUnusedTokens、removeUnusedKeyframes、smartCompoundVariants、treeshakeDesignSystem与propertyFallback五个可选项，全部默认关闭，需要显式开启。

类型包还对外声明了新的约束条件：Panda 2.0 是 ESM-only，需要 Node 22 或更新版本。这一点同样写进了 package.json 的engines: { node: ">=22" }。要迁移既有项目，官方提供 upgrade guide；完整背景可阅读 announcement post。类型包的sideEffects: false（package.json）保证了其可以安全地被 tree-shaking。

破坏性变更一：Qwik JSX 支持移除

2.0.0-beta.20 移除了 Qwik JSX 支持：

• jsxFramework: 'qwik'不再生成styled、Box或 pattern 组件；
• 迁移方式：移除jsxFramework配置，改用css()、cva()与 pattern 函数，在class属性上书写样式。

当前类型包中，JsxFramework联合类型（config.ts）只保留'react' | 'solid' | 'preact' | 'vue'四个成员（声明允许string & {}以便扩展），印证了 Qwik 已从官方支持列表移除。配套的JsxOptions（config.ts）仍提供jsxFactory（默认styled）与jsxStyleProps（'all' | 'minimal' | 'none'，默认all）两个开关，控制生成组件的样式 prop 类型宽度。

破坏性变更二：defineParts 移除与 slot recipe 的替代方案

2.0.0-beta.17 移除了defineParts以及Parts/Part类型。官方建议两种替代：

1. 直接在 recipe 中书写 part 选择器；
2. 使用defineSlotRecipe为每个 part 生成一个类。

如果仍需要defineParts辅助函数，官方给出了一个可自行保留在配置中的最小实现：

const defineParts = <T extends Record<string, { selector: string }>>(parts: T) => (config: Partial<Record<keyof T, SystemStyleObject>>): SystemStyleObject => Object.fromEntries(Object.entries(config).map(([key, value]) => [parts[key].selector, value]))

对照当前源码，slot recipe 的类型面已在 recipe.ts 中完整成型：SlotRecipeDefinition（含slots、base、variants、defaultVariants、compoundVariants）、SlotRecipeVariantFn（接收RecipeSelection返回SlotRecord<S, string>）、SlotRecipeRuntimeFn（附加raw、variantKeys、splitVariantProps、getVariantProps等运行时方法）以及SlotRecipeConfig。这正是"一个 part 一个类"方案的底层类型支撑。

新增一：firstThatWorks() 有序值回退

2.0.0-beta.17 引入firstThatWorks()，用于有序 CSS 值回退：一个属性可以同时携带现代值与受支持值，浏览器按顺序取第一个能生效的：

import { css, firstThatWorks } from 'styled-system/css' css({ color: firstThatWorks('oklch(55% 0.18 250)', '#0057b8') })

生成的 CSS 会同时输出两个值（回退在前、现代值在后）：

.c_firstThatWorks\(oklch\(55\%_0\.18_250\)\,_\#0057b8\) { color: #0057b8; color: oklch(55% 0.18 250); }

使用要点：

• 想要的值写在第一位，思路同 StyleX；
• 成员类型由所在属性决定，因此编辑器自动补全可用，strictTokens依然生效；
• 在配置 recipes 中可从@pandacss/dev导入firstThatWorks，或直接书写firstThatWorks(a, b)值形式。

新增二：keyframes() 局部动画工厂

2.0.0-beta.16 新增keyframes()工厂，用于组件局部内联动画。keyframes({ from: {...}, to: {...} })返回一个kf_…动画名，并在构建时按需产出对应@keyframes块 —— 仅当通过animationName或animation简写被实际引用时才会被 tree-shaken 进输出。其类型签名（system-types.ts）为(keyframe: CssKeyframes[string]) => string，只接受对象形式：裸写animationName: 'spin'已可解析theme.keyframes条目，因此没有命名形式。共享的、属于设计系统的动画仍应放在theme.keyframes（theme.ts）。

新增三：positionTry() 锚点定位回退

2.0.0-beta.16 同时新增positionTry()工厂与theme.positionTry键，用于命名 CSS anchor-positioning 回退，并移除了globalPositionTry。positionTry('bottom')或positionTry({ top: 'anchor(bottom)' })会返回供positionTryFallbacks使用的 dashed-ident，并在构建时按需产出@position-try块。迁移方式：把globalPositionTry条目移到theme.positionTry，通过工厂引用；需要无条件产出且名字手写的块，应放入普通.css文件。

类型层对应为 system-types.ts 的PositionTry（Record<string, SystemStyleObject>）与PositionTryFn，以及 theme.ts 的theme.positionTry字段。

新增四：viewTransition() 与 theme.viewTransitions

View Transitions 支持分两步落地：

2.0.0-beta.10（Minor）：新增viewTransition()。传入 slot 样式，得到稳定的vt_*bag 类，Panda 产出对应的::view-transition-*规则，从styled-system/css导入：

import { viewTransition } from 'styled-system/css' const slide = viewTransition({ group: { animationDuration: '0.4s' }, old: { opacity: 0 }, new: { opacity: 1 }, })

在不同框架中使用：

// React / Next import { ViewTransition } from 'react' ;<ViewTransition name="hero" share={slide}> <img src="…" alt="…" /> </ViewTransition>

<!-- Astro --> <img class="{slide}" transition:name="hero" src="…" alt="…" />

// Solid / Nuxt — framework 启动过渡；你只负责挂 name 与 bag 类 <img class={slide} style={{ viewTransitionName: 'hero' }} src="…" alt="…" />

注意：你仍需要在运行时设置唯一的view-transition-name值 —— Panda 只负责共享 CSS。设计系统的 build info 会携带这些 bags，应用可以直接水合而无需重新提取。

2.0.0-beta.15（Minor）：新增theme.viewTransitions，让 preset 可以命名共享的 view-transition bags。调用viewTransition('slide')时，Panda 内联"vt_slide"；未使用的名字不会进入 CSS。类型对应为 theme.ts 的theme.viewTransitions与 system-types.ts 的ViewTransitionFn。

optimize 与 @property 相关的类型深化

optimize.propertyFallback（2.0.0-beta.15）：会为每个发射的@property注册同时播下一份普通声明，让忽略@property的引擎（Safari 低于 16.4、Firefox 低于 128）依然获得默认值：

export default defineConfig({ optimize: { propertyFallback: true }, })

默认关闭。种子来自存活过剪枝的注册项，因此只为实际用到的变量付费。对应类型在 config.ts 的OptimizeOptions.propertyFallback。

utility 级globalVars（2.0.0-beta.15）：工具定义可以携带globalVars，把变量的@property注册放在写出它的工具旁边。注册会合并进 config 级globalVars，未使用时被剪枝：

utilities: { blur: { className: 'blur', globalVars: { '--blur': { syntax: '*', inherits: false } }, transform: (value) => ({ '--blur': `blur(${value})` }), }, }

类型层：PropertyConfig新增globalVars?: GlobalVarsDefinition字段（utility.ts），GlobalVarsDefinition与CssPropertyDefinition（含syntax、inherits、initialValue）定义在 global-vars.ts。规则细节：

• 在工具已注册的名字上放普通值会在 CSS 发射时告警（仅当 stylesheet 实际读取该变量时）——因为普通值会丢弃注册并让变量开始继承；
• 传完整@property对象可微调某个变量；
• 两个工具注册同名但定义不同是配置错误。

polyfill/--polyfill（2.0.0-beta.10）：原生级联层 polyfill，无需 PostCSS 插件。CssgenOptions.polyfill（config.ts）默认false，--polyfill可覆盖。

optimize.treeshakeDesignSystem（2.0.0-beta.10）：只水合应用实际导入的设计系统模块，而非整个 build-info 产物。--polyfill对应的类型同样位于 config.ts 的OptimizeOptions.treeshakeDesignSystem。

其他配置与钩子变更

cssgen:done钩子回归（2.0.0-beta.9）：作为 observe-only 钩子重新提供，用于获取 CLI、Vite、PostCSS 的最终 CSS；需要修改 CSS 时应使用optimize或 PostCSS。其参数类型CssgenDoneHookArgs包含artifact、content、path、outfile、manifest（含files与tokens）与layerRanges（reset/base/tokens/recipes/utilities 各层的起止范围），见 hooks.ts。

minify顶层配置键（2.0.0-beta.9）：cssgen从配置读取minify，--minify仍可覆盖。对应CssgenOptions.minify（config.ts），默认false。

designSystem采纳（2.0.0-beta.6）：通过designSystem: '@acme/ds'采纳已发布的设计系统。Panda 读取库的panda.lib.json，把其 preset 合并到你的配置之下，并复用其预提取样式。若设计系统需要的 Panda 主版本不同，Panda 会报告明确错误。FileSystemOptions.designSystem字段定义在 config.ts。

preset:resolved修复（2.0.0-beta.1）：修复该钩子缺少utils参数的问题，插件作者现在可在preset:resolved内使用omit/pick/traverse（与config:resolved及 v1 行为一致）。相关类型见 hooks.ts：ConfigResolvedHookUtils提供omit、pick、traverse，而PresetResolvedHookArgs携带preset、name、utils。

移除syntax配置（2.0.0-beta.16）：删除syntax配置项与--syntax标志，template-literal 书写模式随之移除。全部改用对象语法css({ color: 'red' })。当前 config.ts 中已不存在syntax字段。

2.1.x 与稳定性窗口

2.1.0、2.1.1与2.1.2均无类型层面的实质变更（2.1.2 明确标注 "No changes in this release"）。对于 1.x 及更早版本的历史，CHANGELOG 指引读者查看 v1 分支上的 packages/types/CHANGELOG.md。

小结与迁移清单

围绕@pandacss/types的变更可以归纳为四条主线：

1. 书写方式收敛：syntax/ template-literal 移除、Qwik JSX 支持移除、defineParts移除，统一到对象语法 +cva/defineSlotRecipe两条 recipe 路径；
2. 新工厂函数补齐：firstThatWorks()、keyframes()、positionTry()、viewTransition()四个工厂全部在 system-types.ts 中有明确类型签名，且都遵循"按需发射、未用不生成"的 tree-shaking 原则；
3. CSS 变量注册体系成型：@property注册从 config 级globalVars延伸到 utility 级globalVars，配合optimize.propertyFallback解决旧引擎兼容；
4. 构建与集成选项丰富：polyfill、minify、treeshakeDesignSystem、designSystem、cssgen:done钩子，共同构成可观测、可优化的构建链路。

升级到 Panda 2.0 时，建议按此顺序检查：移除syntax与jsxFramework: 'qwik'→ 将defineParts用法迁移到defineSlotRecipe→ 将globalPositionTry迁移到theme.positionTry→ 按需开启optimize各项 → 通过cssgen:done接入最终 CSS 观测。整体上，@pandacss/types在 2.x 中既是配置与生成的类型契约，也是新 CSS 特性的类型化入口，值得在升级过程中逐项对照验证。

• 前端
• 构建工具
• 开发工具