企业官网建设流程全解析

• 移动开发
• 跨平台
• 前端

本篇技术指南以 NativeWind 官方文档 How it works 为骨架，结合仓库源码深入讲解 NativeWind 的编译与运行时原理。读完本文，你将掌握：Web 端为何能直接复用 CSS 类名、原生端如何把 CSS 编译成 StyleSheet 对象、静态/动态样式、Topics 订阅模型、动态单位、状态位掩码（masks）以及子元素样式（child styles）的底层实现机制，并能对照仓库源码定位每一步的具体实现文件。

NativeWind 将 Tailwind CSS 的 utility-first 工作流带入了 React Native 应用（项目描述见仓库根目录 README.md）。它打破了 React Native 传统的内联样式（inline style）范式，改用 CSS 风格语法。但 React Native 并没有 CSS 引擎，那么className="text-black"这样的代码究竟是如何变成{ color: "#000" }的？简单来说，这是一套多步骤的 "smoke and mirrors"（障眼法）过程：先用 Tailwind 生成 CSS，再在构建期把 CSS 编译为 React Native 样式对象，最后通过 JSX transform 在运行时注入。本文按文档脉络逐层拆解。

一、整体工作流：三条管线

从 apps/website/docs/core-concepts/how-it-works.md（v4 文档，与 v2 文档同源）与 v2 文档可以归纳出 NativeWind 的三条核心管线：

1. Tailwind CSS CLI：生成包含应用所需全部 class 的 CSS 文件。NativeWind 会产出两份 StyleSheet——一份用于原生端，一份用于 Web 端，二者都是合法 CSS 文件，可在任意应用中使用。
2. CSS 到 React Native 样式的转换：构建期（build time）解析生成的 CSS，编译为 React Native 样式并注入应用。实现方式是在构建时拦截import './your-styles.css'语句，用生成的 React Native 样式替换它。
3. JSX transform：NativeWind 提供自定义 JSX transform，将默认的jsx函数替换为自定义版本，把 JSX 转换成使用已生成样式的形式。为了避免每个组件都跑一遍样式逻辑带来的开销，处理被延迟到"被标记的"组件（View/Text 等）实际渲染时才执行——在className到达View/Text等原生组件之前，它只是另一个普通 prop。

对应源码入口：自定义 JSX runtime 位于 jsx-runtime.ts，其中jsx、jsxs、jsxDEV均通过wrapJSX包装，注释明确指出"babel 插件会把jsxImportSource切换到这个模块"，且"这些函数是 React 应用中最热门的调用点，必须非常轻量"。

二、Web 端：为什么 className 直接可用

v2 文档明确指出：运行在 Web 上时，NativeWind 直接把样式作为classNameprops 透传，从而可以直接使用 CSS StyleSheet。

原因在于 React Native Web（RNStyleSheet）支持"preprocessed"（预处理）样式——它理解$$css标记。文档给出了 Web 静态运行时的示意代码：

function webStaticRuntime(type, props, key) { // React Native Web supports 'preprocessed' styles, so we don't need to do anything! props.style = { $$css: true, [props.className]: props.className }; delete props.className; return ReactJSXRuntime.jsx(type, props, key); }

即：把className原封不动地转成带$$css: true标记的 style 对象交给 React Native Web，由浏览器原生 CSS 引擎完成后续一切工作。

源码佐证：Web 端的 StyleSheet 实现在 runtime/web/stylesheet.ts，它把通用部分commonStyleSheet与 React Native 自带的RNStyleSheet合并（Object.assign({}, commonStyleSheet, RNStyleSheet)），并通过getComputedStyle(document.documentElement)读取--css-interop-*CSS 变量来提供getFlag能力。注意 Web 端register/registerCompiled/getGlobalStyle均抛出 "not available on web" 错误——这印证了 Web 端不走原生运行时注册管线，样式完全交给真实 CSS。

此外，NativeWind 会给 Tailwind 添加若干插件，使其理解 NativeWind 特有的功能，例如平台变体（platform variants，如ios:、android:、web:前缀）。

三、原生端：把 CSS 编译成 StyleSheet 对象

React Native 没有 CSS 引擎，因此 NativeWind 需要把 CSS 输出处理成 StyleSheet 对象。v2 文档给出的流程是：

NativeWind 用 Tailwind 把你的样式处理成 CSS，然后把该 CSS 编译成 NativeWindStyleObjects，再传给NativeWindStyleSheet.create——一个StyleSheet.create的轻量封装。

对应到当前仓库，原生端的实现核心是 runtime/native/stylesheet.ts：

export const StyleSheet: CssInteropStyleSheet = { getGlobalStyle(name: string) { return getStyle(name); }, register() { throw new Error("Not yet implemented"); }, registerCompiled(options) { return injectData(options); }, getFlag(name) { return flags.get(name)?.toString(); }, };

关键方法是registerCompiled，它把编译产物交给 styles.ts 中的injectData注入运行时。injectData负责：

• 合并rules（样式规则表）；
• 对已经见过的样式（seenStylesForHotReload，支持热更新）重新执行initiateStyle；
• 注入keyframes（动画关键帧）、rootVariables/universalVariables（CSS 变量）；
• 设置 flags 与 rem 基准值（rem.set(data.rem)，默认 14）。

样式数据存放于全局对象global.__css_interop（包含styles、keyframes、rootVariables、universalVariables四个 Map），每条样式是一个Observable<StyleRuleSet>——这正是后面 Topics 订阅模型的载体。

3.1 静态样式（Static styles）

文档示例：

<Text class="text-black" />; NativeWindStyleSheet.create({ "text-black": { color: "#000", }, });

NativeWindStyleSheet.create()看起来与 React Native 的StyleSheet.create()非常相似。底层上，这些静态样式会被传入StyleSheet.create()并缓存。由于值在编译期就已确定，运行时只需要查表、无需任何响应式求值。

四、动态样式：atRules 与响应式求值

很多样式无法在编译期确定为单一值，比如 Tailwind 的container类：它有一个基础样式container，外加多组基于 atRules（媒体查询）的变体。文档示例：

<View class="container" />; NativeWindStyleSheet.create({ styles: { container: { width: "100%", }, "container@0": { maxWidth: 640, }, "container@1": { maxWidth: 768, }, "container@2": { maxWidth: 1024, }, "container@3": { maxWidth: 1280, }, "container@4": { maxWidth: 1536, }, "font-bold": { fontWeight: "700", }, }, atRules: { container: [ [["media", "(min-width: 640px)"]], [["media", "(min-width: 768px)"]], [["media", "(min-width: 1024px)"]], [["media", "(min-width: 1280px)"]], [["media", "(min-width: 1536px)"]], ], }, topics: { container: ["width"], }, });

这里有几个关键约定，必须理解：

• @{n}后缀：container@0中的@0是该原子样式所属 atRule 的索引（下标从 0 开始）。当该 atRule 的条件被满足时，对应变体样式才会被应用。
• atRules 表：atRules.container是一个数组，每个元素对应一组条件（如["media", "(min-width: 640px)"]表示"宽度 ≥ 640px 的媒体查询"）。
• Topics 表：topics.container = ["width"]表示container样式订阅了width这个 topic。

4.1 运行时如何判断条件

原生端并没有媒体查询能力，所以必须先断言查询条件再应用样式。文档给出了简化版逻辑：根据Dimensions.get("window").width与minWidth/maxWidth比较决定样式是否生效，并强调：

媒体查询是响应式的（reactive），如果条件将来可能被满足，需要重渲染组件。为此 NativeWind 使用细粒度响应式（fine grain reactivity），样式可以订阅特定事件，如Dimensions或Appearance。

源码佐证：条件求值的真实实现在 runtime/native/conditions.ts，核心是testRule，它按顺序测试四类条件，任一不通过即返回false：

• pseudoClasses：testPseudoClasses读取共享状态里的hover/active/focus（对应 UI 状态类如active:、hover:）；
• media：testMediaQueries逐条testMediaQuery，通过testCondition/testFeature处理min-width、max-width、prefers-color-scheme、orientation、resolution（按约 160dp/英寸换算）、prefers-reduced-motion、ltr/rtl（基于I18nManager.isRTL）等特征；
• containerQuery：testContainerQuery支持容器查询，从refs.containers中按名字（默认容器名为DEFAULT_CONTAINER_NAME）查找容器并测试其 layout 尺寸；
• attrs：testAttributes测试组件属性条件（如data-*属性）。

其中testPseudoClasses的注释说明了编译约束："State 应该已经有 hover、active、focus，如果没有，说明编译器出了问题。"而宽度/高度比较通过可观察对象vw/vh（见 unit-observables.ts 同目录）在读取时建立依赖，实现响应式重求值。

五、Topics：订阅模型

container的例子已经引入了 Topics 概念。文档明确：

NativeWind 基于订阅模型工作，样式可以订阅 topics。这里container样式订阅了widthtopic，因此每当应用的宽度变化，样式都会被重新求值。

源码佐证：在 styles.ts 中，每个样式是Observable<StyleRuleSet>；getStyle(name, effect)会通过obs.get(effect)读取，同时把effect.dependencies记录进去。Observable实现在 observable.ts，读取时收集依赖、变更时触发订阅者重渲染——这就是"样式订阅 topic、topic 变化触发样式重求值"的底层机制。useColorScheme（见 runtime/native/api.ts）也是同样的模式：创建带run回调的 effect，读取colorScheme可观察对象以建立依赖，颜色方案变化时自动重渲染。

六、动态单位（Dynamic Units）

Topics 不仅服务于 atRules，还能实现动态单位。文档示例：

<View class="w-screen" />; NativeWindStyleSheet.create({ styles: { "w-screen": { width: 100, }, }, topics: { "w-screen": ["width"], }, units: { "w-screen": { width: "vw" }, }, });

w-screen的宽度是100vw。编译产物中基础值为100，但units表声明了它的单位是视口宽度（vw）——由于它订阅了widthtopic，每当视口宽度变化，运行时都会用当前视口宽度重新计算实际像素值。

源码佐证：视口单位可观察对象vw/vh定义在 unit-observables.ts，conditions.ts中媒体查询的conditionReference默认就是{ width: vw, height: vh }，宽度比较会读取vw.get(effect)建立依赖。此外仓库还支持rem单位，injectData会通过rem.set(data.rem)设置基准（默认 14px）。

七、状态条件：位掩码（masks）快速求值

样式可以是条件性的，取决于组件或应用的状态。文档示例：

<Text class="text-black ios:text-blue-500" />; NativeWindStyleSheet.create({ styles: { "text-black": { color: "#000", }, "ios:text-blue-500": { color: "rgb(59 130 246)", }, }, masks: { "ios:text-blue-500": 8192, }, });

文档说明：

条件可以是 UI 状态（active/hover）、颜色方案（light/dark）、平台（ios/android/web）等。这些条件在编译期被预计算成位掩码（bitmask），以便运行时快速求值。

8192即1 << 13，是编译期分配给"平台为 iOS"这一条件的位。运行时只需对当前环境的条件位掩码做一次按位与（bitwise AND）即可判断该样式是否生效，无需逐个字符串比较。

源码佐证：条件测试的快速路径由 conditions.ts 的testRule承担，而编译期把伪类条件编码进规则的方式，可以从样式规则结构（StyleRule中的pseudoClasses、media、containerQuery、attrs字段）推断：这些条件在编译阶段归一化、在运行时逐类断言。testPseudoClasses从共享状态读取 hover/active/focus 的 observable 值——即文档所说"预计算为位掩码"之外的运行时状态来源。

八、子元素样式（Child Styles）

有些样式不是作用于组件自身，而是作用于它的子元素。文档示例：

<Text class="divide-x" />; NativeWindStyleSheet.create({ styles: { "divide-x-2.children@0": { borderLeftWidth: 2, borderRightWidth: 0, }, }, atRules: { "divide-x-2.children": [[["selector", "(> *:not(:first-child))"]]], }, childClasses: { "divide-x-2": ["divide-x-2.children"], }, });

这里divide-x-2对应 Tailwind 的 divide 系列工具类（用于在子元素之间绘制分隔线）。要点：

• childClasses：声明divide-x-2这个类会把divide-x-2.children分发给子元素；
• selector atRule：(> *:not(:first-child))表示"直接子元素且非第一个"，对应 CSS 选择器语义；
• 编译产物中divide-x-2.children@0的@0同样是该样式所属 atRule 的索引。

仓库中该类工具的实际编译与测试可参考 spacing.tsx（divide 系列断言）以及 v4 文档 space-between.mdx，其中 v4 文档也使用了*:not(:first-child)选择器语法描述分隔线实现。

九、原生运行时：动态样式如何工作

综合 v2 与 v4 文档，原生端区分静态与动态样式：动态样式要么带条件，要么其值在组件渲染前无法确定（如md:text-red、w-screen）。文档给出的动态样式求值简化版逻辑是：拆分 classNames → 查表 → 按特异性排序（specificityCompareFn）→ 过滤不满足媒体条件的条目。v4 文档还补充了完整 JSX 运行时示意：

const globalStyles = new Map<string, StyleObject>(); function nativeStaticRuntime(type, props, key) { props.style = props.className .split(" ") .map((className) => globalStyles.get(className)) .sort(specificityCompareFn); delete props.className; if (styles.some((style) => style.isDynamic)) { // 动态样式需要运行时 HOC props.$$as = type; return ReactJSXRuntime.jsx(NativeWindWrapper, props, key); } else { return ReactJSXRuntime.jsx(type, props, key); } }

其中specificityCompareFn对应样式特异性排序——这与 style-specificity.mdx 中讲解的"相同属性按来源顺序/特异性决定谁生效"一致。

源码佐证：

• interopComponentsMap（见 runtime/native/api.ts）存放cssInterop/remapProps生成的包装组件，wrapJSX在 JSX 调用时查找该 Map 决定是否走 NativeWind 逻辑——这与文档中transforms.set(View / Text)的 WeakMap 示意对应。
• 真正的渲染逻辑在 runtime/native/render-component.tsx 的renderComponent：当样式使用伪类时（state.pressable），会把View升级为Pressable；当样式含动画/过渡时（state.animated），会包装react-native-reanimated的useAnimatedStyle；当使用 CSS 变量时（state.variables）会注入VariableContext。三种升级都要求发生在初始渲染，否则会重挂载组件并打印警告。
• 文档结论部分强调："如果你在应用里看到这样的代码，它略非标准，但并不奇怪"——即把className拆分成样式数组再传给styleprop。这正是 NativeWind 为你自动完成的事情：styled(View)之类 HOC 的等价物。

十、总结与延伸阅读

一句话概括 NativeWind 的原理：构建期把 Tailwind CSS 编译为样式表数据并注入运行时，运行时通过自定义 JSX transform 把className解析成 React Native 的style，静态样式直接查表缓存，动态样式通过 Observable 订阅模型（Topics）在条件/尺寸/外观变化时精细重求值。

这与"你自己手写styled(View)HOC"是同一件事，只是 NativeWind 自动替你完成了。

想继续深入，可以按以下路径阅读当前仓库：

• 自定义 JSX runtime 入口：jsx-runtime.ts
• 原生样式注册与注入：runtime/native/stylesheet.ts、runtime/native/styles.ts
• 条件求值引擎：runtime/native/conditions.ts
• 响应式组件渲染：runtime/native/render-component.tsx
• Web 端 StyleSheet：runtime/web/stylesheet.ts
• 配套测试用例：packages/nativewind/src/tests/ 下的spacing.tsx、states.tsx、transforms.tsx、dark-mode.ios.tsx等，覆盖了本文涉及的 divide、状态、动态单位与暗色模式行为
• 相关官方文档：v2 版 How it works 与最新版 core-concepts/how-it-works.md、style-specificity.mdx

• 移动开发
• 跨平台
• 前端