企业官网建设流程全解析

@emotion/babel-preset-css-prop 深度指南：一行配置开启 css prop 的 Babel Preset 全解析

【免费下载链接】emotion👩‍🎤 CSS-in-JS library designed for high performance style composition项目地址: https://gitcode.com/gh_mirrors/em/emotion

@emotion/babel-preset-css-prop是 Emotion 官方提供的 Babel Preset，用于在采用classic JSX runtime的项目中，通过一行presets配置为整个项目自动启用cssprop：编译后 JSX 调用从React.createElement切换为 Emotion 的jsx工厂函数，样式对象在编译期被静态化并生成带 hash 的类名。本文以该 preset 的 CHANGELOG 为骨架，结合其源码、测试快照与官方文档，系统讲解安装配置、选项语义、编译产物形态，以及从 10.x 到 11.x 的关键破坏性变更与迁移路径，帮助你既会用、也理解它为什么这么设计。

一、这个 Preset 到底做了什么：三个插件的组合编排

从源码结构看，@emotion/babel-preset-css-prop本身并不实现任何转换逻辑，而是一个"装配器"：它把三个插件按固定顺序组合起来，并把用户传入的选项分发给对应插件。入口文件 的核心逻辑非常直白：

export default (api, { pragma, sourceMap, autoLabel, labelFormat, importMap, ...options } = {}) => { if (options.runtime) { throw new Error( 'The `runtime` option has been removed. ...' ) } return { plugins: [ [pragmatic, { export: 'jsx', module: '@emotion/react', import: pragmaName }], [jsx, { pragma: pragmaName, pragmaFrag: 'React.Fragment', ...options }], [emotion, { sourceMap, autoLabel, labelFormat, cssPropOptimization: true, importMap }] ] } }

三个插件各司其职：

1. @emotion/babel-plugin-jsx-pragmatic：在编译产物中自动注入import { jsx as ___EmotionJSX } from '@emotion/react'语句（源码见 jsx-pragmatic 实现，它只在检测到JSXElement/JSXFragment时才追加导入，且插入在既有 import 之后以避免与 polyfill 出现顺序问题——这正是 10.0.23 版本修复的行为）。
2. @babel/plugin-transform-react-jsx：负责真正的 JSX 转换，把 pragma 指向___EmotionJSX，Fragment 指向React.Fragment；其余选项（如useBuiltIns、throwIfNamespace）原样透传。源码注释明确说明这种"解构出 Emotion 专属选项、其余全透传"的设计是为了向前兼容：@babel/plugin-transform-react-jsx未来新增选项会自动生效。
3. @emotion/babel-plugin：处理cssprop 与css/styled调用的样式静态化，其中cssPropOptimization: true被强制开启，确保 css prop 走最优化的编译路径。

此外，package.json 中exports字段限定了可导入的文件范围（11.10.0 引入），同时保持对main/module兼容入口；peerDependencies 要求@babel/core >= 7。

二、安装与三种使用方式

2.1 安装

yarn add @emotion/babel-preset-css-prop # 或 npm install @emotion/babel-preset-css-prop

2.2 方式一：Babel 配置文件（推荐）

在.babelrc或babel.config.js中：

{ "presets": ["@emotion/babel-preset-css-prop"] }

注意两个关键约束：

• 该 preset 已内置 emotion 插件，原.babelrc中的@emotion/babel-plugin（或旧版babel-plugin-emotion）条目应删除，其选项移到 preset 里；若同时保留会造成重复转换。
• 若你同时使用@babel/preset-react或@babel/preset-typescript，@emotion/babel-preset-css-prop必须放在它们之后，以确保 JSX pragma 相关转换按正确顺序执行。

选项迁移示例（来自 README）：

{ + "presets": [ + [ + "@emotion/babel-preset-css-prop", + { + "autoLabel": "dev-only", + "labelFormat": "[local]" + } + ] + ], - "plugins": [ - [ - "@emotion", - { - "autoLabel": "dev-only", - "labelFormat": "[local]" - } - ] - ] }

2.3 方式二：Babel CLI

babel --presets @emotion/babel-preset-css-prop script.js

2.4 方式三：Node API

require('@babel/core').transform(code, { presets: ['@emotion/babel-preset-css-prop'] })

2.5 适用边界：新 JSX runtime 用户不要用这个 preset

官方 css prop 文档 明确指出：该 preset 只服务于 classic JSX runtime。若你使用 React>= 16.14.0并想用新 JSX runtime（runtime: "automatic"），应改为@babel/preset-react配合@emotion/babel-plugin：

{ "presets": [ ["@babel/preset-react", { "runtime": "automatic", "importSource": "@emotion/react" }] ], "plugins": ["@emotion/babel-plugin"] }

Next.js 用户则需在其next/babelpreset 内嵌配置：

{ "presets": [ ["next/babel", { "preset-react": { "runtime": "automatic", "importSource": "@emotion/react" } }] ], "plugins": ["@emotion/babel-plugin"] }

不兼容警告：该 preset 与@babel/plugin-transform-react-inline-elements不兼容，二者同时使用会导致cssprop 样式无法正确生效。另外，它不适用于禁止自定义 Babel 配置的项目（如 Create React App），这类项目应改用文件顶部的/** @jsx jsx */pragma 方式。

三、编译产物剖析：从<a css={{...}}>到___EmotionJSX

3.1 官方文档示例

README 给出了完整的"输入 → 输出"对照。输入：

const Link = props => ( <a css={{ color: 'hotpink', '&:hover': { color: 'darkorchid' } }} {...props} /> )

输出（经简化）：

import { jsx as ___EmotionJSX } from '@emotion/react' var _ref = process.env.NODE_ENV === 'production' ? { name: '1fpk7dx-Link', styles: 'color:hotpink;&:hover{color:darkorchid;}label:Link;' } : { name: '1fpk7dx-Link', styles: 'color:hotpink;&:hover{color:darkorchid;}label:Link;', map: '/*# sourceMappingURL=data:application/json;... */' } const Link = props => ___EmotionJSX('a', _extends({ css: _ref }, props))

3.2 从测试快照看真实产物细节

仓库测试tests/index.js 通过babel-tester对 fixture 做快照断言，index.js.snap 揭示了若干实现细节：

• 自动注入导入：import { jsx as ___EmotionJSX } from "@emotion/react";会被追加到文件已有 import 之后。
• 双环境产物：样式对象以process.env.NODE_ENV === "production"三元表达式区分——生产分支只有name和styles（无 sourcemap、无 label 冗余），开发分支额外携带map（内联 source map）和toString报错提示函数。
• 开发期防误用提示：产物中包含_EMOTION_STRINGIFIED_CSS_ERROR__函数，当开发者不小心把css函数返回的对象当普通对象（如用作className）stringify 时给出明确报错。这是 10.0.23 引入的 dev hint。
• label 拼接：开发分支的 styles 形如color:hotpink;label:Button;，label 以;开头衔接——这是 10.0.22 修复的"声明块末尾缺分号导致 label 粘连"问题，修复方式就是给 label 字符串加前导分号。

四、选项全解：Emotion 专属选项与 JSX 选项透传

该 preset 同时接受@emotion/babel-plugin与@babel/plugin-transform-react-jsx的选项，前者被显式解构，后者通过剩余参数透传。

4.1autoLabel：三值枚举（11.0.0 起）

重大变更（11.0.0）：autoLabel不再是布尔值，改为三个字符串值，默认dev-only：

从 快照 可以看到dev-only的实际效果：生产分支 styles 只有color:hotpink，开发分支则多出;label:Button;。

4.2labelFormat：字符串模板或函数

• 字符串模板：支持[local]、[filename]、[dirname]三个占位符。label 计算逻辑见 label.js：[local]取组件/变量标识符，[filename]取文件名（index会被替换为所在目录名），[dirname]取文件所在目录的 basename；非法的 CSS 类名字符统一被清洗为-。
• 函数（11.0.0 起）：labelFormat可以是一个函数，接收{ name, path }后返回自定义字符串，实现任意 label 规则。

测试用例 options-are-used.js 用labelFormat: '[dirname]--[filename]--[local]'验证了模板展开，对应快照 中生成了label:__fixtures__--array-css-prop--Component;这样的完整路径式 label。

4.3importMap：替换已废弃的instances（11.0.0 起）

importMap用于告诉 emotion 插件"哪些导入路径应被视为 Emotion 的导出"，从而在你 re-export Emotion API 的项目中仍能命中转换。11.0.0 移除了旧的instances选项，所有使用处应迁移到importMap（CHANGELOG 中该变更与importMap引入是同一个 PR）。

4.4sourceMap

布尔值，控制是否生成开发环境的样式 source map（对应产物中的map字段）。测试用例中显式传sourceMap: false以观察 label 行为差异。

4.5 透传给 JSX 插件的选项

useBuiltIns、throwIfNamespace、pragma等其余选项直接转发给@babel/plugin-transform-react-jsx。README 给出的完整示例（均为默认值演示）：

{ "presets": [ [ "@emotion/babel-preset-css-prop", { "autoLabel": "dev-only", "labelFormat": "[local]", "useBuiltIns": false, "throwIfNamespace": true } ] ] }

4.6 被移除的runtime选项

如果你在配置中仍写"runtime": "automatic"，preset 会直接抛出异常（src/index.js#L16-L20），错误信息会指引你改用@babel/preset-react+@emotion/babel-plugin的组合。这个选项的生命周期详见下文。

五、CHANGELOG 主线：10.x → 11.x 的关键演进与迁移

关联文档 CHANGELOG 记录了该 preset 从 10.0.14 到 11.12.0 的完整演进，以下按主题梳理（外部 commit/PR 链接不在此展开，请直接查看仓库中的 CHANGELOG 原文）：

5.1runtime选项：引入 → 弃用 → 移除

• 10.1.0：新增runtime选项，可配置为'automatic'以启用新 JSX runtime（需兼容版本的 React）。
• 10.2.0：该选项被弃用。原因在于 preset 内部已包含 JSX 转换插件，再配runtime: "automatic"会导致 Babel 配置中 JSX 插件重复、产生难以排查的问题，且某些 preset 隐式包含 JSX 插件时问题更隐蔽。官方建议直接用@babel/preset-react+babel-plugin-emotion替代。
• 11.0.0：正式移除。配置残留runtime会直接抛错。同时，10.2.1 曾修复一个相关问题：只有runtime: "automatic"时才会根据development选项使用@babel/plugin-transform-react-jsx-development，classic runtime 与该插件不兼容。

迁移路径（10.x → 11.x 必读）：

- "presets": [["@emotion/babel-preset-css-prop", { "runtime": "automatic" }]] + "presets": [["@babel/preset-react", { "runtime": "automatic", "importSource": "@emotion/react" }]], + "plugins": ["@emotion/babel-plugin"]

5.2instances→importMap

11.0.0 移除instances选项，统一由importMap承担"声明 Emotion 别名导入"的职责，语义更明确，也覆盖了 re-export 场景。

5.3autoLabel从布尔改为三值

见上文 4.1，这是 11.0.0 的另一项破坏性变更。旧写法autoLabel: true/false需改为'dev-only'/'always'/'never'。

5.4 数组形式 css prop 的转换调整（11.0.0）

调整了传给 css prop 的数组的转换方式，使数组中的函数元素能在运行时被解析——即css={[base, ({ theme }) => theme.color]}这类依赖 props/theme 的样式对象可以在运行时求值，而静态对象仍被编译期优化。对应 fixture 见 array-css-prop.js，快照显示css={[{ color: 'green' }]}被编译为___EmotionJSX("div", _extends({ css: _ref }, props))。

5.5 工程与分发层面的演进

• 10.0.27：补充 LICENSE 文件（仓库遵循 MIT，见 package.json）。
• 10.0.22：label 字符串加前导分号，避免声明块末尾无分号时的粘连问题。
• 10.0.23：@emotion/core导入插入到已有 import 之后，避免与 polyfill 的顺序冲突；同时加入"css 对象被意外 stringify"的开发期提示。
• 11.10.0：package.json增加exports字段，限制可导入文件范围，同时尽量保留公共 API 的导入路径。
• 11.11.0：修复 Node ESM 环境下的导入问题。
• 11.12.0：更新依赖@emotion/babel-plugin@11.12.0与@emotion/babel-plugin-jsx-pragmatic@0.3.0。

六、验证与测试：快照如何保证转换行为稳定

该 preset 的测试策略值得借鉴：通过自定义的babel-tester工具，以真实 Babel 配置跑 fixture 并做快照断言。

• 测试入口tests/index.js 直接以 preset 本身作为presets配置运行。
• 两个 fixture（index.js 含 Fragment 与展开属性的 Button、array-css-prop.js 含数组 css prop）覆盖了典型场景。
• 第二个测试文件 options-are-used.js 专门验证sourceMap与labelFormat选项确实被消费并反映在产物中。

对比 index.js.snap 与 options-are-used.js.snap 可以直观看到：默认labelFormat: '[local]'时 label 是Button，而自定义模板后变成__fixtures__--__fixtures__--Button。这类快照把"preset 组装是否正确、选项是否透传、产物是否含 sourcemap/label"全部固化为可回归的契约。

七、常见问题速查

八、总结

@emotion/babel-preset-css-prop的定位非常清晰：它是 classic JSX runtime 下"一键启用 css prop"的便捷入口，内部通过jsx-pragmatic（注入 Emotion jsx 导入）→plugin-transform-react-jsx（切换 JSX 工厂）→@emotion/babel-plugin（静态化样式对象）三插件协作完成转换；其演进主线（runtime引入又移除、instances让位importMap、autoLabel布尔改三值、labelFormat支持函数）反映的是 Emotion 团队对"配置正交性"与"新 JSX runtime 兼容性"的持续收敛。理解这份 CHANGELOG，等于同时理解了 preset 的全部选项边界与 10.x 升级 11.x 的完整迁移地图；而对照 源码 与 测试快照，你就能准确预判任意配置组合的编译产物形态。

【免费下载链接】emotion👩‍🎤 CSS-in-JS library designed for high performance style composition项目地址: https://gitcode.com/gh_mirrors/em/emotion