Maas-Model-platform/docs/inside/tailwind-migration.md

Tailwind CSS 本地化迁移文档

问题描述

症状： 首次访问时偶发样式丢失，刷新后恢复正常

原因： 使用 CDN 版本的 Tailwind CSS (https://cdn.tailwindcss.com)

CDN 方式的问题

1. 网络延迟：CDN 加载需要时间，样式可能在组件渲染后才加载完成
2. 加载顺序：React 组件可能在 Tailwind 加载前就渲染，导致无样式闪烁
3. 缓存依赖：首次访问无缓存，后续访问有缓存所以正常
4. CDN 不稳定：外部 CDN 可能偶尔不可用或响应慢
5. 无法自定义：CDN 版本无法使用自定义配置

解决方案

将 Tailwind CSS 从 CDN 迁移到本地构建，样式打包到 bundle 中。

实施日期

2026-01-31

修改内容

1. 创建 tailwind.config.js

export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "./*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./hooks/**/*.{js,ts,jsx,tsx}",
    "./contexts/**/*.{js,ts,jsx,tsx}",
    "./utils/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter', ...],
      },
      animation: {
        'wave-h': 'wave-h 2s ease-in-out infinite',
        'wave-v': 'wave-v 2s ease-in-out infinite',
      },
    },
  },
  plugins: [],
}

作用：

• 配置 Tailwind 扫描的文件路径
• 自定义主题（字体、动画等）
• 支持 Tree-shaking，只打包使用的样式

2. 创建 postcss.config.js

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

作用：

• 配置 PostCSS 处理 Tailwind 指令
• 自动添加浏览器前缀

3. 创建 index.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/* 全局样式和自定义动画 */

作用：

• 导入 Tailwind 的基础样式、组件和工具类
• 定义全局样式和自定义动画
• 这个文件会被 Vite 处理并打包

4. 修改 index.tsx

import './index.css';  // 新增

作用：

• 在应用入口导入样式
• 确保样式在组件渲染前加载

5. 修改 index.html

<!-- 删除 -->
<script src="https://cdn.tailwindcss.com"></script>

<!-- 删除内联样式 -->
<style>...</style>

作用：

• 移除 CDN 依赖
• 样式现在通过 CSS 文件导入

优势对比

特性	CDN 方式	本地构建
首次加载速度	❌ 慢（需下载 CDN）	✅ 快（已打包）
样式稳定性	❌ 依赖网络	✅ 本地保证
自定义配置	❌ 不支持	✅ 完全支持
生产体积	❌ 大（完整库）	✅ 小（Tree-shaking）
离线可用	❌ 不可用	✅ 可用
构建时间	✅ 无需构建	⚠️ 略增加

验证步骤

1. 重启开发服务器

# 停止当前服务器（Ctrl+C）
# 重新启动
npm run dev

2. 清除浏览器缓存

• 打开开发者工具（F12）
• 右键点击刷新按钮
• 选择"清空缓存并硬性重新加载"

3. 测试首次访问

• 打开隐私/无痕模式
• 访问应用
• 检查样式是否立即加载

4. 检查构建产物

npm run build

检查 dist 目录中是否有 CSS 文件被打包。

预期效果

✅ 首次访问样式立即加载

• 样式已打包到 bundle 中
• 不依赖外部 CDN

✅ 无样式闪烁（FOUC）

• CSS 在 HTML 解析时就开始加载
• 组件渲染时样式已就绪

✅ 离线可用

• 所有资源都在本地
• 不需要网络连接

✅ 更小的生产体积

• Tree-shaking 移除未使用的样式
• 通常比 CDN 版本小 80%+

注意事项

1. 开发服务器需要重启

   • 修改配置文件后必须重启 Vite

2. 样式变化需要刷新

   • Tailwind 配置变化后需要刷新浏览器

3. 内容路径要正确

   • tailwind.config.js 中的 content 路径必须包含所有使用 Tailwind 的文件

4. 自定义样式位置

   • 全局样式放在 index.css
   • 组件样式使用 Tailwind 类名

故障排查

问题：样式完全不显示

解决：

# 1. 检查是否导入了 index.css
# 2. 重启开发服务器
npm run dev

# 3. 清除 node_modules/.vite 缓存
rm -rf node_modules/.vite
npm run dev

问题：某些样式不生效

解决：

• 检查 tailwind.config.js 的 content 路径
• 确保文件路径被包含在扫描范围内

问题：构建后样式丢失

解决：

• 检查生产构建：npm run build
• 检查 dist 目录是否有 CSS 文件
• 确保 index.html 正确引用了 CSS

性能对比

开发环境

• CDN 方式：首次加载 ~300KB（完整库）
• 本地构建：首次加载 ~50KB（按需生成）

生产环境

• CDN 方式：~300KB（完整库，无 Tree-shaking）
• 本地构建：~20-50KB（Tree-shaking 后）

参考资料

• Tailwind CSS 官方文档
• Vite + Tailwind 集成指南
• PostCSS 配置