企业官网建设流程全解析

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

本篇技术指南深入剖析 Panda CSS 的配置合并机制：extend决定一项配置是追加到既有预设之上，还是整体替换它命名的条目。合并全部发生在 TypeScript 侧的packages/config/src/merge.ts，早于createConfigSnapshot把配置降级（lower）为 Rust 编译器快照。读完本文，你将掌握裸写键与extend的语义差异、themeRegistryKeys的边界设计、preset 与用户配置的优先级排序规则，以及presets: []与插件在“删除条目”这个不可表达场景中的正确用法。

合并发生在哪里：TypeScript 侧、Rust 之前

Panda CSS 的配置是 JavaScript/TypeScript 模块，可以包含函数（patterns、hooks、presets、plugins），因此 Rust 端只消费序列化后的快照，不负责执行任意用户配置。合并发生在 packages/config/src/merge.ts 中，纯 TypeScript 实现，在createConfigSnapshot把函数降级为{ kind: 'js-callback', id }引用、把RegExp降级为{ kind: 'regex', ... }之前完成。

核心入口是mergeConfigs(configs: ExtendableConfig[])，它按顺序接收一份扁平配置列表（presets 在前、用户配置最后），产出单一的合并结果：

// packages/config/src/merge.ts export function mergeConfigs(configs: ExtendableConfig[]): Dict

另一条带SourceTracker的重载mergeConfigsWithSources在合并的同时记录每个值来自哪个 preset/config，支撑 sources.ts 的可选来源追踪（trackSources: true时启用）。

extend 与裸写的核心二分

合并语义只有一条规则，却决定了整个配置系统的行为：

• 把主题键写在theme.extend下 → 与既有内容合并；
• 直接把键写在theme下 →替换它。

写一个键就替换它、写进extend就并进去。这正是文档中「Replacement lands on the entry you name」的起点：合并器不知道你想保留 preset 的哪些部分，所以它用「位置」来编码意图——extend是唯一表达「保留既有、叠加新增」的方式。

替换落在你命名的条目上：themeRegistryKeys

theme.tokens与theme.recipes这类键持有命名条目（named entries），因此一份配置替换的是「你点名的那个条目」，而不是它上方的整段键。这是合并语义中最反直觉也最关键的一点：

theme: { tokens: { colors: { brand: { value: '#EA8433' } } }, // 只替换 colors 的 brand，spacing 不受影响 recipes: { button: myButton }, // 只替换 button 这个 recipe，card 不受影响 }

在 merge.ts 中，这个边界由themeRegistryKeys显式登记：

const themeRegistryKeys = new Set([ 'tokens', 'semanticTokens', 'keyframes', 'recipes', 'slotRecipes', 'textStyles', 'layerStyles', 'animationStyles', 'viewTransitions', 'positionTry', ])

处理这些键的分支是applySectionBase→isRegistry(sectionName, key, value)→replaceRegistryEntries：先取目标上已累积的注册表对象，再对注册表中的每个名字执行replaceValue。也就是说，对一个 registry 键，合并粒度是「条目」而不是「整段键」。

tokens 与 recipes 的粒度差异：scale 与 recipe

themeRegistryKeys不是任意挑选的，它精确记录了「你点名的东西在哪一层停止」：

• 对recipes，停止点就是recipe 本身——button、card各自是完整的命名对象，替换button不影响card；
• 对tokens，停止点是scale（色彩刻度、间距刻度等）——因为你不可能逐条目命名单个 token：一个 token（如brand.value）如果作为条目来替换，与「合并进它」将无法区分。所以 token 的最小替换单位是colors、spacing这样的 scale 层。

这解释了为什么下面这段配置能精确「只动 brand 色」：

theme: { tokens: { colors: { brand: { value: '#EA8433' } } }, }

合并后colors.brand被替换，而colors下其他刻度（如 preset 定义的全部色彩）原样保留。

breakpoints 为何被刻意排除

breakpoints故意缺席themeRegistryKeys。原因很直接：一个 breakpoint 的值是字符串，对字符串做「逐条目替换」在结果上与「合并」完全等价——preset 定义sm: '640px'，你写sm: '600px'，无论是替换还是合并，结果都一样。既然无法靠「条目粒度」区分，逐条目替换就永远无法删除preset 定义的那一组 breakpoint。因此breakpoints走整体替换路径（replaceValue），写一次就整段覆盖。

应用顺序与优先级：后来的配置赢

合并的顺序决定了谁能覆盖谁：

1. presets（按config.presets中的声明顺序）；
2. designSystem 链，从根到叶（designSystem命名的层级）；
3. 用户配置最后。

在每一份单独配置内部，先应用它的base 键，再应用它的extend 键。整体遵循「后来的赢」（later configs win）。

这条顺序在 preset.ts 的collectConfigs中体现为深度优先收集：先递归解析并压入预设，最后才ctx.configs.push(config)压入用户配置；mergeConfigs按列表顺序依次覆盖。测试 preset.test.ts 用「preset base / preset extend / user base / user extend」四层优先级验证了最终结果：accent（extend 定义）由用户胜出，brand（base 定义）由用户胜出，preset 独有条目完整保留。

一次被否决的草案：为什么不与 v1 / Tailwind 对齐

早期草案曾把所有extend先收集起来，在所有 base 之后统一应用——这与 v1 和 Tailwind 的行为一致。但这个方案被回退了，原因很微妙：

它会让一个 preset 的extend覆盖用户自己对同一键的裸写，这与「裸写一个键就是替换」的语义直接矛盾。

换句话说：如果全局先跑 base 再跑 extend，preset 的extend.tokens.colors.brand会盖掉用户裸写的theme.tokens.colors.brand，用户根本无法用最直白的方式覆盖 preset。这里的取舍是**「你的配置胜过 preset」比「与 v1 对等」更重要**——用户配置排在最后、且按「base 后 extend」逐配置应用，保证用户裸写永远是最终裁决。

数组语义：base 替换、extend 拼接

在mergeValue中，数组的合并模式随位置变化（merge.ts）：

• base 键中的数组 → 替换既有数组；
• extend 键中的数组 → 与既有数组拼接（concat）。

这是唯一一个 extend 不是「纯对象键合并」的场景：extend 里的数组会追加而不是覆盖，例如theme.extend.recipes之外的列表类配置（如 staticCss 的某些数组字段）可以通过 extend 持续累积。

对象键的合并：逐键递归

除数组外，mergeValue对两个普通对象执行逐键递归合并：preset 的colors.brand若是一个含value、description、extensions的对象，用户 extend 只写value，则其余字段保留。token 的扁平属性（value、description、type、deprecated、extensions）在合并后还会被normalizeNestedTokens提升进DEFAULT桶，保证「既带子 token 又带自身 value」的写法语义稳定（见 merge.ts）。

设计后果：单层注册表的固有权衡

「一个单层注册表只能做到粒度细或可清空，不能两者兼得」——这是这套语义最值得记住的结论：

• 能覆盖一个：per-entry 替换让你精确覆盖单个 keyframe、单个 recipe、单个 token scale；
• 不能删一组：因为替换单位是条目，你无法表达「删掉 preset 的整组 keyframes」；
• presets: []是唯一的干净起点：需要完全脱离 preset 的某个部分时，不引用该 preset 从源头解决问题；
• 删除单个条目不可表达（not expressible）：theme下既没有删除运算符，extend也无法「减去」一个键。

因此「移除一个条目」在文档层面被明确指向插件：插件 hook（如preset:resolved、config:resolved，见 config-loading-design.md）可以在合并前后修改配置对象，实现delete这类合并器表达不了的操作。从源码结构看，这正是 preset.ts 中runPresetResolvedHooks把预设结果交还给插件逐层改写、再由collectConfigs压栈的原因。

成本与调用点：每次配置加载都发生

合并的成本极低。设计文档给出的实测参考是：两个内置 preset 加一份用户配置，约 0.74ms，每次配置加载会调用数次。

从源码看调用点集中在 preset.ts：

• resolveAuthoredPresetsForLoad中至少四个位置调用mergeConfigs（含mergeConfigsWithSources）：
  • designSystem 链的每一层内（normalizeClassNameOptions(mergeConfigs(ctx.configs) ...)）各一次；
  • resolveConfigEntry收敛单个配置条目的结果时一次；
  • 最终合并全部 configs 时一次；
• 其中一次位于 designSystem 循环内部，意味着 designSystem 链越深，每多一层就多一次全量重合并（re-merge per level）。

在@pandacss/config的整体管线中，合并发生在「bundle 用户配置 → 解析 authored presets + 折叠 extend → 运行 hooks → 应用默认值 → 序列化」这一链条的中间（详见 config-loading-design.md 的流程示意图），因此它只对 JS 侧加载路径有成本，Rust 端拿到的是已经合并、序列化完毕的快照。

未解决的问题与演进方向

设计文档明确记录了一个未排期的更大变更（unresolved）：

显式运算符（replace()用于替换、null用于删除）会把意图放在值上，而不是用「写在哪里」来位置化编码意图。这样就不再需要themeRegistryKeys这份登记表，也让「删除条目」变得可表达。

这是一次更大的接口变更，目前没有排期。它指出了当前语义的两种备选哲学：

只要现状保持，写作配置时就需要记住一条心法：在能条目的地方裸写只动条目，在不能条目的地方（breakpoints、整体 section）裸写即整体替换；想保留 preset 的积累就放进extend，想清零就presets: []，想删条目就写插件。

延伸阅读

• design-system-manifest：designSystem 链与 manifest 的形态，理解「根到叶」层级从何而来；
• config-loading-design：完整的加载 → 预设解析 → 序列化 → Rust 快照管线，及来源追踪与依赖跟踪设计；
• 合并实现：packages/config/src/merge.ts；
• 预设解析与调用点：packages/config/src/preset.ts；
• 优先级与嵌套预设测试：packages/config/tests/preset.test.ts；
• 来源追踪实现：packages/config/src/sources.ts。

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