企业官网建设流程全解析

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

@pandacss/vite是 Panda CSS 官方提供的 Vite 集成插件，它把编译器直接内联到构建流程中，让开发者在无需独立 codegen 步骤的情况下即可完成样式提取、样式表注入与热更新。本文以该包的 CHANGELOG 为主线，结合插件源码、单元测试与仓库内的真实沙箱示例，梳理从 2.0 预览版到 2.1.2 的关键演进脉络，并给出可直接落地的配置与使用方案。读完本文，你将掌握插件的全部选项语义、生命周期钩子的执行细节、HMR 行为以及如何在项目里开启源码转换（source transform）。

插件定位：无需单独 codegen 的内联编译器

在 Panda CSS 2.0 之前，使用 Vite 需要借助@pandacss/postcss或独立运行pandaCLI 来生成样式系统。而在 2.0 之后，@pandacss/vite以 Vite 插件的形式把编译器内联进开发服务器与构建流程，正如 packages/vite/README.md 所述："The Vite plugin for Panda CSS, with an inline compiler — no separate codegen step required"。

从 package.json 可以看到该包的关键约束：

• ESM-only，"type": "module"；
• 运行环境要求Node >= 22（与 Panda 2.0 的整体要求一致）；
• 依赖@pandacss/compiler、@pandacss/compiler-shared、@pandacss/transformer三个 workspace 内包；
• 对 Vite 的 peer 依赖为>=6.0.0，仓库自身在 devDependencies 中使用 Vite 7.3.6 进行测试。

安装方式很简单：

npm install -D @pandacss/vite

然后在vite.config.ts中注册：

// vite.config.ts import { defineConfig } from 'vite' import panda from '@pandacss/vite' export default defineConfig({ plugins: [panda()], })

插件选项全解析：cwd、configPath、outdir 与 transform

pandacss()接受的配置对象定义在 packages/vite/src/index.ts 的PandaPluginOptions接口中，共四个选项：

从源码看，configResolved钩子中插件会依次执行：

cwd = cwdOption ?? config.root driver = await createNodeDriver({ cwd, configPath }) if (transformEnabled) resolveSourceTransformer() outdir = outdirOption codegen() driver.parseFiles()

其中codegen()对应driver.codegen({ cwd, outdir })，会把 styled-system 运行时与类型声明写入磁盘。测试 plugin.test.ts 明确验证了启动后styled-system/css/index.js与styled-system/types/index.d.ts均存在。

值得注意的细节：outdir一旦在插件层面显式传入，就会固定下来；而如果没有传，则跟随配置文件在hotUpdate重载后更新——测试uses the reloaded config outdir when no plugin outdir override is set验证了这一点（plugin.test.ts）。

生命周期钩子：插件在 Vite 中的工作方式

插件对象以name: 'pandacss'、enforce: 'pre'注册，保证在任何用户插件之前运行。它主要依赖三个 Vite 钩子（packages/vite/src/index.ts）：

configResolved：初始化 Driver 与首轮 codegen

在 Vite 配置解析完成后，插件创建 Node 驱动（createNodeDriver），执行一次 codegen 与全量文件解析。这一步保证了开发服务器一启动，样式系统代码就绪。

transform（order: 'pre'）：源码转换 + 样式表注入

transform钩子有两层职责：

1. 源码转换：当transform: true时，先对非 CSS 文件执行runSourceTransform，把静态css()/ recipe / pattern /styled()调用重写为 class 字符串，这样样式运行时可以从最终 bundle 中剥离（见 CHANGELOG 2.0.0 的 "Source transforms" 条目）。
2. 样式表注入：对.css文件，先用driver.compiler.hasLayerDeclaration(code)判断是否声明了 Panda 的@layer reset, base, tokens, recipes, utilities。只有声明了 layer 的 CSS 文件（即用户真正的 CSS 入口）才被当作样式根（root），并追加编译出的driver.cssgen(...)输出。用户原有 CSS 会被原样保留，测试断言了这一点（plugin.test.ts）。

hotUpdate：细粒度的 HMR 处理

hotUpdate钩子是插件的核心复杂度所在，它把变更文件分为三类处理：

• 设计系统文件（driver.isDesignSystemFile）：区分artifact与source两种变更。artifact 变更触发codegen()重跑；source 变更则通过driver.syncDesignSystemFileChange同步，二者都使样式根失效但不触发整页刷新。
• 配置文件（driver.isConfigFile）：调用driver.reload()，若配置有变更则清空 watch 文件集合、重新 codegen、重新解析源码，并发送full-reload使页面整体重载。
• 源码文件（driver.isSourceFile）：通过driver.applyChange增量更新编译产物，只使样式根失效，保持热更新。

HMR 期间插件用invalidateRoots与withInvalidatedRoots维护 client 与 SSR 两套模块图的一致性——测试invalidates the stylesheet root in the SSR module graph too验证了 SSR 环境的样式根也会被同步失效（plugin.test.ts）。

2.0.0 主版本：Rust 引擎与插件能力全面升级

CHANGELOG 中信息量最大的部分是 2.0.0 的 Major Changes（packages/vite/CHANGELOG.md）。它说明 Panda 2.0 用基于 Oxc 的 Rust 引擎替换了旧的编译器——你仍然编写相同的css()、recipes、patterns、tokens 与 JSX props，但底层实现完全不同：

• 单次解析每个文件（one parse per file），支持跨文件的值解析，原生输出 CSS，构建流程中不再有ts-morph或 PostCSS；
• 更快的构建：提取阶段快 15–37 倍，watch 模式约 360 倍，staticCss约 85 倍（这些数字来自官方公告，属项目自述数据）；
• 更轻量的生成类型：TypeScript 类型实例化数量减少约 99%；
• 更快的运行时：css()与 recipes 对重复样式做 memoize，最多约 4 倍提速；
• Node 与浏览器共用同一引擎：@pandacss/compiler-wasm在浏览器中运行同一引擎并产生相同的 CSS。

对 Vite 用户直接相关的新能力包括：

• Bundler plugins：@pandacss/vite、@pandacss/webpack、@pandacss/rollup、@pandacss/bun都在构建内运行 Panda；
• Source transforms：开启transform: true后，静态样式调用被改写为 class 字符串，样式运行时从 bundle 中消失；
• 更小的 CSS：通过optimize选项移除未使用的 tokens 与 keyframes、只生成用到的 compound variants、并支持设计系统 tree-shaking；
• 可发布的设计系统：用panda lib编写，用designSystem消费，应用侧无需重新提取；
• 新工具函数：viewTransition()、firstThatWorks()、keyframes()、positionTry()以及 mask、scrollbar、pointer/validity 条件等基础 preset 新工具。

同时，2.0.0 明确标注：Panda 2.0 仅支持 ESM，且需要 Node 22 或更新版本。

从 2.0.1 到 2.1.2：修复与告警收敛

主版本发布后的几个小版本值得关注：

2.0.1：补齐 Svelte / Vue / Astro 的静态样式编译

f9459ce修复了pandacss({ transform: true })在 Vite 构建期间对.svelte、.vue、.astro文件中的静态样式调用进行编译的问题——这补上了此前源码转换只覆盖常规 JS/TSX 文件的缺口。

2.0.0-beta.10：transform 保持 opt-in，polyfill 原生化

预览版最后阶段的两个关键调整（packages/vite/CHANGELOG.md）：

• 源码转换始终留在transform: true开关之后；Vite 在编译器重载后会重建自己的 transformer，避免 HMR 持有过期的重写器；
• Rollup 插件会报告编译器诊断并在出错时让构建失败，而不是静默输出 CSS。

同版本还新增了原生 cascade-layer polyfill，通过polyfill选项（CLI 为--polyfill）启用，不再需要 PostCSS 插件。在 Vite 插件源码中对应driver.config.polyfill === true时的处理：cssgen 输出层声明，入口 CSS 用driver.compiler.stripLayerOrderStatements(code)剥离原有的 layer 顺序语句（packages/vite/src/index.ts）。

2.1.0：nested_property 告警与去重

• nested_property警告：当样式被嵌套在既不是条件也不是选择器的键下时（如css({ has: { svg: { color: 'red' } } })），这些样式实际上永远不会生效。新警告会建议修正写法，例如'&:has(svg)'。
• 告警去重：Vite 与 Bun 插件不再在"解析文件时"与"构建样式表时"重复打印同一条警告。

测试对这两点都有覆盖：reports a broken nested style once when the transform and the stylesheet both see it断言nested_property只出现一次（plugin.test.ts）；keeps previous CSS and reports diagnostics when source syntax breaks则验证了解析出错时保留上一次成功的 CSS 且诊断只打印一次（plugin.test.ts）。

2.1.1 / 2.1.2：依赖跟随更新

这两个版本没有独立的插件改动，仅是随@pandacss/compiler、@pandacss/transformer、@pandacss/compiler-shared的同步升级。这也提示了一个升级习惯：@pandacss/vite与这三个依赖包需保持同版本号一起升级。

诊断系统：编译问题如何到达你的终端

插件使用createDiagnosticLog()创建去重的诊断日志器，并在三条路径上输出：

1. 源码转换期间：while transforming source（携带onlyNew: true保证不重复）；
2. 样式表编译期间：while compiling the stylesheet；
3. 源码解析期间：while parsing <file>，通过driver.compiler.getFile(ctx.file)?.diagnostics读取该文件的最新诊断（packages/vite/src/index.ts）。

例如当源码出现语法错误时，日志形如：

panda: 1 diagnostic(s) while parsing <root>/App.tsx warning js_parse_error <root>/App.tsx:3:55 Unexpected token. Panda could not fully parse this file; some styles may be missing.

同时保留上一次成功的 CSS 输出，避免开发过程中出现样式闪失。

设计系统热更新与 monorepo 支持

hotUpdate中对设计系统的支持是 2.0 的重要新增能力。插件通过driver.designSystemWatchTargets()注册设计系统的manifestPath、buildInfoPath、presetPath与sourceFiles为 watch 目标（packages/vite/src/index.ts）。单元测试中的 mock 展示了典型路径：

/project/node_modules/@acme/ds/panda/lib.json /project/node_modules/@acme/ds/panda/buildinfo.json /project/node_modules/@acme/ds/panda/preset.mjs /project/node_modules/@acme/ds/src/button.css.ts

当设计系统 artifact（如lib.json）变化时，触发 codegen 重跑并失效样式根；当设计系统源码变化时，只同步编译状态而不重跑 codegen——测试regenerates codegen when a design-system artifact changes与skips codegen when a design-system source file changes分别锁定了这两条路径（plugin-unit.test.ts）。

对 monorepo，插件同样支持include覆盖到 Vite 根目录之外的同级包源码。集成测试regenerates CSS when a sibling package file included with ../ changes验证了通过../相对路径与绝对路径两种方式引入的外部源码文件变更都能触发样式再生成（plugin.test.ts）。这归功于addPandaWatchFiles：它基于driver.watchTargets()（解析过的文件、源码目录、配置文件）逐个调用 Vite 的addWatchFile，并用watchedFilesSet 保证不重复注册（packages/vite/src/index.ts）。

实战示例：sandbox/vite-ts 的完整配置

仓库中的 sandbox/vite-ts 沙箱是@pandacss/vite的完整可运行范例。其 vite.config.ts 开启了源码转换：

import pandacss from '@pandacss/vite' import react from '@vitejs/plugin-react' import { defineConfig } from 'vite' const ANALYZE = !!process.env.ANALYZE export default defineConfig({ plugins: [pandacss({ transform: true }), react()], build: { sourcemap: ANALYZE, }, resolve: { conditions: ['source'], }, })

对应的 panda.config.ts 展示了与插件协同的典型配置面：presets、preflight、optimize（移除未用 tokens/keyframes）、staticCss、include/exclude、outdir: 'styled-system'、jsxFramework: 'react'以及 recipes、globalCss、viewTransitions、positionTry 等主题内容。

其中的 SourceTransformProof.tsx 组件专门用于验证源码转换效果——它混合使用了css()、sva()（slot recipe）、HStack/Wrap/Circle/Square/Box等 JSX 工厂、panda.footerJSX 标签、gridpattern 与token()函数。在transform: true下，这些静态调用会在构建期被折叠为 class 字符串，运行时只需极小的开销。

升级与迁移注意事项

根据 CHANGELOG 与包定义，迁移到 2.x 的 Vite 集成时需注意：

1. Node 版本：@pandacss/vite要求 Node >= 22，2.0 是 ESM-only；
2. Vite 版本：peer 依赖要求 Vite >= 6.0.0；
3. 升级路径：跟随官方 v1 → v2 升级指南迁移项目配置；
4. transform 是显式 opt-in：默认false，CSS 注入、codegen 与 HMR 始终运行，但源码重写必须显式开启；
5. 插件三个依赖包需同步升级：@pandacss/compiler、@pandacss/transformer、@pandacss/compiler-shared在 CHANGELOG 中始终以相同的版本号伴随发布。

如果你在升级过程中遇到样式消失，可优先检查是否触发了nested_property警告（把嵌套样式改写为&:has(...)等合法选择器写法），并确认include是否覆盖了实际写样式源码的目录。

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