HelloWorld 与 WindiCSS 集成指南

把 HelloWorld 项目和 WindiCSS 结合起来，最直接的流程是：用 Vite 创建项目、安装 vite-plugin-windicss 与 windicss、在 vite 配置里启用插件、在入口文件引入 virtual 样式（import ‘virtual:windi.css’），根据需要在 windi.config.js 中开启 attributify、shortcuts、safelist 等配置，开发时配合 devtools 和 JIT 即可高效开发和按需生成样式。

先聊聊为什么选 WindiCSS

如果只说结论，WindiCSS 是一种“按需生成、类名驱动”的原子化 CSS 方案，和 Tailwind 思路类似但更偏向即时编译（JIT）、对模板语言提取更友好、并内置一些便捷特性（如属性化写法 attributify）。对小而频繁变更的 HelloWorld 示例项目来说，它能让你快速写出可读性高、体积小的样式，同时开发体验流畅。

WindiCSS 的关键特性

• 按需生成（JIT/即时编译）：只编译你在模板中实际使用的类，减少输出体积并加快迭代。
• attributify 模式：可以使用属性而不是 class 来写样式，提升可读性。
• shortcuts / aliases：把常用类组合封装成短名，减少重复。
• 插件与生态：有 Vite、Nuxt、Webpack 等插件，开发者工具支持也比较完善。

准备工作（工具与版本要求）

在开始之前，确认环境：

• Node.js：建议 14 及以上（具体项目可按需）
• 包管理工具：npm / yarn / pnpm 任意其一
• 构建工具：本文以 Vite 为例，适配 Vue、React、Svelte 等框架

一步步把 HelloWorld 与 WindiCSS 集成

1. 创建 HelloWorld 项目（Vite）

这里给出两个常见模版：Vue 和 React。你也可以用自己熟悉的框架。

// Vue
npm create vite@latest helloworld -- --template vue
// React
npm create vite@latest helloworld -- --template react

创建完成后进入目录并安装依赖：

cd helloworld
npm install

2. 安装 WindiCSS 和 Vite 插件

安装官方推荐的包：

npm install -D windicss vite-plugin-windicss

为什么是这两个包？windicss 提供核心功能，vite-plugin-windicss 把它挂到 Vite 的编译流程中，负责按需扫描和生成样式。

3. 配置 Vite（vite.config.js / vite.config.ts）

在 Vite 配置中引入插件，例（简洁示范）：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue' // 或 react
import WindiCSS from 'vite-plugin-windicss'
export default defineConfig({
plugins: [
vue(),
WindiCSS()
]
})

如果你使用 TypeScript 配置（vite.config.ts），语法类似。这样在开发模式下，Windi 会实时扫描文件并生成对应的样式。

4. 添加 windi.config.js（可选但推荐）

在项目根目录创建 windi.config.js，用来定制主题、shortcut、提取器等。例如：

module.exports = {
  attributify: true,
  extract: {
    include: ['index.html', 'src//*.{vue,js,ts,jsx,tsx,html}'],
    exclude: ['node_modules', '.git']
  },
  theme: {
    extend: {
      colors: {
        brand: '#1f8ef1'
      }
    }
  },
  shortcuts: {
    'btn': 'px-4 py-2 rounded bg-brand text-white hover:opacity-90'
  },
  safelist: 'prose prose-sm m-auto'.split(' ')
}

几点说明：

• attributify：启用后可以用属性化语法（例如 <button bg=”brand” p=”2″ />）。
• extract.include：告知扫描器哪些文件要被扫描，确保模板里的类能被识别和生成。
• shortcuts：把常用类组合封成单个名字，提高复用性。
• safelist：对动态生成的类或者运行时拼接的类，用 safelist 保证它们不会被丢弃。

5. 在入口文件引入虚拟样式

这是一个常见且必要的步骤：在 main.js / main.ts / main.jsx 中加入下面一行：

import 'virtual:windi.css'

它让 Vite 插件注入生成的样式到页面，开发环境和构建后都能生效。开发时也可以引入 devtools：

import 'virtual:windi-devtools'

在组件里使用 WindiCSS（示例）

Vue 组件示例（HelloWorld.vue）

<template>
  <div class="min-h-screen flex items-center justify-center bg-gray-50">
    <button class="btn" @click="count++">Clicked {{ count }} times</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

这里使用了我们在配置里定义的 shortcut（btn），让样式更语义化。

React 示例（App.jsx）

export default function App() {
  const [count, setCount] = useState(0)
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <button className="px-4 py-2 rounded bg-brand text-white hover:opacity-90"
        onClick={() => setCount(c => c + 1)}>
        Clicked {count} times
      </button>
    </div>
  )
}

attributify 模式：另一种写法

如果你对属性化语法感兴趣（更接近 HTML 属性而不是长 class 列表），在 windi.config.js 启用后可以这样写：

<button p="2" rounded bg="brand" text="white" hover:opacity="90">Click</button>

好处是更简洁、更具可读性；但也有学习成本，需要适应属性命名约定。

生产构建与按需提取（Prune / Purge）

WindiCSS 的按需生成机制在构建（build）时通常会工作得很好，但有几点要注意：

• 确认 extract.include 覆盖了所有模板文件（比如 markdown、字符串模板、第三方组件中的内联模板等）。
• 运行时根据条件拼接类名（如 `class={‘text-‘ + color}`）时，编译器无法静态识别，需要把可能用到的类放到 safelist 或者使用显式映射。
• 查看构建输出，确认最终 CSS 文件大小符合预期；如果异常大，检查是否误加入了大量未使用类。

常见问题与排查方法

• 样式没生效：检查是否在入口引入了 virtual:windi.css，以及 vite-plugin-windicss 是否在 plugins 数组中。
• 动态类丢失：把动态生成的类添加到 safelist，或改写为显式映射。
• attributify 无效果：确认 windi.config.js 里有 attributify: true，并重启开发服务器。
• 编译慢或报错：检查 extract 的 include/exclude 是否配置合理，避免扫描大量无关文件。

高级用法与优化技巧

• shortcuts + design tokens：把品牌色、间距、常用按钮样式放到 shortcuts，便于跨组件统一修改。
• 插件扩展：Windi 支持扩展插件，例如用于表单、排版（typography）的插件，可以在 config 中注册。
• IDE 插件：使用 Windi/UnoCSS 的 VS Code 扩展能在编辑时预览类的样式，减少来回刷新查看。
• 分包与缓存：在大型项目中，把公用样式抽成短名并结合缓存策略，减少重复生成开销。

一个小技巧：调试动态类

如果你有一段代码运行时拼接类名，可以临时在某个开发组件里写出所有可能的类（放在注释或隐藏元素），让扫描器在开发时识别到它们，随后再迁移到 safelist。是有点“笨”的办法，但有效——在没有提前设计好映射表时特别实用。

配置文件与文件结构一览

一些做法与反思（写给刚上手的人）

我在给新手演示时常常会先用最直接的 class 写法把东西摆出来，然后逐步把重复的类抽成 shortcuts，再考虑是否启用 attributify。这样做可以避免一下子被配置文件淹没——先看到效果，再优化结构。其实我自己也常常这么干，项目越小越想快，但一旦想长期维护，就会把魔法字串收拢到配置里。

收尾提醒（那些容易被忽视的小点）

• 在 CI/CD 中构建时，确保 NODE_ENV 正确，否则有些按需行为可能不一致。
• 使用第三方组件库时，注意类名可能和 Windi 的扫描规则冲突，尽量把外部模板也加入 extract.include。
• 时常检查最终 CSS 大小，过度放行 safelist 也会造成体积膨胀。

好了，以上就是把 HelloWorld 项目和 WindiCSS 结合的全流程与常见实践。按我上面的步骤去做，遇到具体问题再针对性调整配置就行——一旦熟悉了提取规则和 safelist 的使用，开发速度会快得让你惊讶，代码也会更整洁一些。接下来就把手头的 HelloWorld 拉起来试试吧，反正最好的理解方式是动手改一个颜色、加个按钮，然后看它瞬间生效的那一刻。