❌

普通视图

发现新文章，点击刷新页面。
昨天 — 2025年12月31日首页

Vue 3 插件系统重构实战：从过度设计到精简高效

✇掘金 前端
作者 大象的鼻子那么长
2025年12月31日 09:29

一次基于 YAGNI 原则的架构优化之旅，代码减少 26.5%，启动速度提升 35%

前言

在维护一个大型 Vue 3 企业级项目时，我发现应用启动越来越慢，插件系统的代码也越来越臃肿。经过深入分析，我意识到问题的根源在于过度设计——我们实现了很多"可能会用到"的功能，但实际上从未使用过。

这篇文章将分享我如何通过应用 YAGNI（You Aren't Gonna Need It）原则，将一个 837 行的插件系统重构为 615 行，同时将启动时间从 1500ms 优化到 980ms 的完整过程。

一、问题诊断：过度设计的代价

1.1 症状表现

在开始重构前，我们的插件系统存在以下问题：

性能问题：

  • 首次渲染时间：~1200ms
  • 插件安装耗时：~300ms
  • 初始内存占用：~45MB

代码问题：

  • 插件管理器 425 行，职责不清
  • 类型定义 150 行，充斥着 any 类型
  • 初始化流程混乱，同步异步混杂

1.2 深层原因分析

通过代码审查和使用率统计，我发现了几个关键问题：

问题一：实现了完整的插件生命周期，但使用率极低

// 旧架构：定义了 5 个生命周期钩子
interface PluginLifecycle {
  register?: () => void    // 使用率: 0%
  install: () => void      // 使用率: 100%
  enable?: () => void      // 使用率: 0%
  disable?: () => void     // 使用率: 0%
  uninstall?: () => void   // 使用率: 0%
}

统计显示，除了 install 方法，其他生命周期钩子的使用率为 0%。这意味着我们维护了大量永远不会被调用的代码。

问题二：EventEmitter 增加了复杂度，但收益有限

// 旧架构：使用 EventEmitter 管理插件事件
class PluginManager extends EventEmitter {
  async install(name: string) {
    this.emit('before:install', name)
    // ... 安装逻辑
    this.emit('after:install', name)
  }
}

// 实际使用：没有任何地方监听这些事件
// 搜索结果：0 个 .on('before:install') 调用

EventEmitter 带来了额外的内存开销和复杂度，但没有任何实际价值。

问题三：类型安全性差

// 旧架构：大量使用 any 类型
interface PluginDefinition {
  install: (app: App, options?: any) => void  // ❌ any 类型
  defaultOptions?: any                         // ❌ any 类型
}

// 导致的问题：
pluginManager.install('myPlugin', { 
  typoInOptionName: true  // 编译时无法发现错误
})

1.3 性能瓶颈定位

使用 Chrome DevTools Performance 分析，我发现了几个关键瓶颈：

  1. 插件管理器初始化：创建 EventEmitter、初始化状态管理 → 80ms
  2. 依赖检查逻辑：遍历插件依赖树（实际没有依赖） → 45ms
  3. 生命周期钩子调用：触发空的事件监听器 → 30ms

这些都是可以避免的开销。

二、设计原则：YAGNI 与职责分离

2.1 YAGNI 原则的应用

YAGNI（You Aren't Gonna Need It）是极限编程的核心原则之一，意思是"你不会需要它"。在重构中，我严格遵循这个原则：

删除决策矩阵：

功能 当前使用率 未来可能性 决策
install 生命周期 100% 必需 ✅ 保留
enable/disable 0% 低 ❌ 删除
uninstall 0% 低 ❌ 删除
EventEmitter 0% 低 ❌ 删除
依赖检查 0% 中 ❌ 删除（用 priority 替代）
状态管理 20% 中 ✅ 简化（只保留 installed 集合）

2.2 职责分离原则

旧架构的 PluginManager 承担了太多职责：

// 旧架构：PluginManager 做了太多事情
class PluginManager {
  // 职责1: 插件注册
  register(plugin: PluginDefinition) { }
  
  // 职责2: 插件安装
  install(name: string) { }
  
  // 职责3: 生命周期管理
  enable(name: string) { }
  disable(name: string) { }
  
  // 职责4: 依赖管理
  checkDependencies(name: string) { }
  
  // 职责5: 事件管理
  emit(event: string) { }
  on(event: string, handler: Function) { }
  
  // 职责6: 状态查询
  isInstalled(name: string) { }
  getStatus(name: string) { }
}

新架构将职责清晰分离：

// 新架构：职责清晰分离

// 1. 类型定义（src/plugins/core/types.ts）
export interface PluginDefinition<T = any> {
  metadata: PluginMetadata
  defaultOptions?: T
  install: PluginInstallFn<T>
}

// 2. 插件安装器（src/plugins/core/installer.ts）
export class PluginInstaller {
  register(plugin: PluginDefinition): void
  async installOne(app: App, name: string): Promise<PluginInstallResult>
  async installAll(app: App, config: PluginConfigMap): Promise<PluginInstallResult[]>
}

// 3. 插件注册中心（src/plugins/registry.ts）
export function getAllPlugins(): PluginDefinition[]
export function getDefaultPluginConfig(): PluginConfigMap

// 4. 应用初始化器（src/bootstrap/app-initializer.ts）
export class AppInitializer {
  async initPlugins(app: App): Promise<InitResult>
  async loadStyles(): Promise<InitResult>
  async initFeatures(app: App, router: Router): Promise<InitResult>
}

每个模块只做一件事，职责清晰，易于测试和维护。

2.3 类型安全优先

新架构使用 TypeScript 泛型实现强类型约束：

// 新架构：强类型插件定义
export interface PluginDefinition<T = any> {
  readonly metadata: PluginMetadata
  readonly defaultOptions?: T
  install: PluginInstallFn<T>
}

// 使用示例：编译时类型检查
interface PiniaOptions {
  enablePersistence: boolean
  enableDevtools: boolean
}

const piniaPlugin: PluginDefinition<PiniaOptions> = {
  metadata: { name: 'pinia', version: '1.0.0' },
  defaultOptions: {
    enablePersistence: true,
    enableDevtools: false,
  },
  install(app, options) {
    // options 类型为 PiniaOptions，有完整的智能提示
    if (options.enablePersistence) { }
  }
}

三、架构设计：分层与分阶段

3.1 新架构分层设计

src/
├── plugins/
│   ├── core/                    # 核心层
│   │   ├── types.ts            # 类型定义（80行）
│   │   └── installer.ts        # 插件安装器（180行）
│   ├── registry.ts             # 注册层（45行）
│   ├── piniaStateManager.ts    # 具体插件
│   ├── i18nSystem.ts
│   └── consoleInterceptor.ts
├── bootstrap/
│   └── app-initializer.ts      # 初始化层（250行）
└── main.ts                      # 入口层（140行）

分层职责：

  1. 核心层（Core）：提供插件系统的基础能力

    • 类型定义：定义插件接口和配置类型
    • 插件安装器：负责插件的注册和安装

  2. 注册层（Registry）：管理插件清单和默认配置

    • 插件列表：返回所有可用插件
    • 默认配置：提供插件的默认选项

  3. 初始化层（Bootstrap）：协调应用启动流程

    • 分阶段初始化：核心 → 插件 → 样式 → 功能
    • 错误处理：统一的错误捕获和降级策略

  4. 入口层（Main）：应用启动入口

    • 核心依赖初始化：Vue、Router、Pinia、i18n
    • 调用初始化器：启动应用

3.2 分阶段初始化流程

新架构采用清晰的分阶段初始化策略：

// 初始化阶段定义
export enum InitPhase {
  CORE = 'core',           // 核心依赖（阻塞渲染）
  PLUGINS = 'plugins',     // 插件系统（阻塞渲染）
  STYLES = 'styles',       // 样式资源（不阻塞交互）
  FEATURES = 'features',   // 非关键功能（不阻塞交互）
}

启动时序图：

时间轴 ────────────────────────────────────────────────────>
       │
       ├─ 1. 初始化核心依赖（同步，阻塞）
       │    ├─ 创建 Vue 应用
       │    ├─ 安装 Router、Pinia、i18n
       │    └─ 注册全局指令和组件
       │
       ├─ 2. 挂载应用到 DOM（同步，阻塞）
       │    └─ app.mount('#app')  ← 用户看到界面
       │
       ├─ 3. 初始化插件系统（异步，不阻塞渲染）
       │    ├─ 注册所有插件
       │    └─ 按优先级安装插件
       │
       ├─ 4. 加载样式资源（异步，不阻塞交互）
       │    ├─ 加载 SCSS 样式
       │    └─ 加载图标字体
       │
       └─ 5. 初始化非关键功能（异步，不阻塞交互）
            ├─ 错误处理系统
            ├─ 资源预加载器
            └─ 性能监控

关键优化点：

  1. 尽早挂载：核心依赖初始化后立即挂载，让用户尽快看到界面
  2. 异步加载：插件、样式、功能模块异步加载，不阻塞首次渲染
  3. 降级启动：如果插件安装失败，仍能启动核心功能

3.3 错误处理与降级策略

async function bootstrap() {
  try {
    // 1. 初始化核心依赖（必须成功）
    const app = initCore()
    
    // 2. 挂载应用（必须成功）
    app.mount('#app')
    
    // 3. 初始化插件（失败则降级）
    const initializer = new AppInitializer()
    await initializer.initPlugins(app)
    
    // 4. 加载样式（失败不影响功能）
    initializer.loadStyles().catch(error => {
      logger.warn('样式加载失败', error)
    })
    
    // 5. 初始化功能（失败不影响核心）
    initializer.initFeatures(app, router).catch(error => {
      logger.warn('功能初始化失败', error)
    })
  } catch (error) {
    // 降级启动：只加载核心功能
    logger.warn('尝试降级启动')
    const app = initCore()
    app.mount('#app')
  }
}

四、核心实现：从理论到代码

4.1 类型定义：强类型约束

// src/plugins/core/types.ts

/**
 * 插件安装函数
 */
export type PluginInstallFn<T = any> = (
  app: App, 
  options?: T
) => void | Promise<void>

/**
 * 插件元数据
 */
export interface PluginMetadata {
  readonly name: string           // 插件唯一标识
  readonly version: string         // 插件版本
  readonly description?: string    // 插件描述
  readonly core?: boolean          // 是否为核心插件
  readonly priority?: number       // 安装优先级（越小越先安装）
}

/**
 * 插件定义
 */
export interface PluginDefinition<T = any> {
  readonly metadata: PluginMetadata
  readonly defaultOptions?: T
  install: PluginInstallFn<T>
}

/**
 * 插件安装结果
 */
export interface PluginInstallResult {
  name: string
  success: boolean
  duration: number
  error?: Error
}

设计亮点：

  1. 泛型约束：PluginDefinition<T> 使用泛型约束配置类型
  2. 只读属性：readonly 防止元数据被意外修改
  3. 可选属性：? 标记非必需字段，减少样板代码
  4. 结果类型：PluginInstallResult 提供详细的安装反馈

4.2 插件安装器：轻量高效

// src/plugins/core/installer.ts

export class PluginInstaller {
  private readonly plugins = new Map<string, PluginDefinition>()
  private readonly installed = new Set<string>()
  private readonly options: Required<InstallerOptions>

  constructor(options: InstallerOptions = {}) {
    this.options = {
      debug: import.meta.env.DEV,
      timeout: 10000,
      ...options,
    }
  }

  /**
   * 注册插件
   */
  register(plugin: PluginDefinition): void {
    if (this.plugins.has(plugin.metadata.name)) {
      logger.warn(`插件 ${plugin.metadata.name} 已注册，将被覆盖`)
    }
    this.plugins.set(plugin.metadata.name, plugin)
  }

  /**
   * 安装单个插件（带超时保护）
   */
  async installOne(
    app: App,
    name: string,
    config?: any,
  ): Promise<PluginInstallResult> {
    const startTime = performance.now()
    const plugin = this.plugins.get(name)

    if (!plugin) {
      return {
        name,
        success: false,
        duration: performance.now() - startTime,
        error: new Error(`插件 ${name} 未注册`),
      }
    }

    try {
      const options = { ...plugin.defaultOptions, ...config }
      
      // 关键：带超时的安装，防止插件卡死
      await Promise.race([
        plugin.install(app, options),
        new Promise((_, reject) =>
          setTimeout(() => reject(new Error('安装超时')), this.options.timeout),
        ),
      ])

      this.installed.add(name)
      return { 
        name, 
        success: true, 
        duration: performance.now() - startTime 
      }
    } catch (error) {
      return {
        name,
        success: false,
        duration: performance.now() - startTime,
        error: error as Error,
      }
    }
  }
}

设计亮点：

  1. Map + Set 数据结构：

    • Map<string, PluginDefinition> 存储插件定义，O(1) 查找
    • Set<string> 存储已安装插件，O(1) 去重检查

  2. 超时保护：使用 Promise.race 防止插件安装卡死

  3. 详细的结果反馈：返回 PluginInstallResult 包含成功状态、耗时、错误信息

  4. 核心插件保护：

// 核心插件安装失败则抛出错误，阻止应用启动
if (!result.success && plugin.metadata.core) {
  throw new Error(`核心插件 ${plugin.metadata.name} 安装失败`)
}

4.3 应用初始化器：分阶段协调

// src/bootstrap/app-initializer.ts

export class AppInitializer {
  private readonly results: InitResult[] = []
  public readonly pluginInstaller: PluginInstaller

  /**
   * 初始化插件系统
   */
  async initPlugins(app: App): Promise<InitResult> {
    const startTime = performance.now()

    try {
      // 1. 注册所有插件
      const plugins = getAllPlugins()
      this.pluginInstaller.registerAll(plugins)

      // 2. 安装所有插件（按优先级排序）
      const config = getDefaultPluginConfig()
      await this.pluginInstaller.installAll(app, config)

      const duration = performance.now() - startTime
      logger.info(`✓ 插件系统初始化完成 (${duration.toFixed(2)}ms)`)

      return { phase: InitPhase.PLUGINS, success: true, duration }
    } catch (error) {
      logger.error('✗ 插件系统初始化失败', error)
      throw error
    }
  }

  /**
   * 加载样式资源（允许部分失败）
   */
  async loadStyles(): Promise<InitResult> {
    const styleModules = [
      () => import('@/assets/styles/var.scss'),
      () => import('@/assets/styles/index.scss'),
      () => import('@/assets/iconfont/iconfont.css'),
    ]

    // 并行加载，使用 Promise.allSettled 允许部分失败
    const results = await Promise.allSettled(
      styleModules.map(fn => this.retryImport(fn, 3)),
    )

    const failed = results.filter(r => r.status === 'rejected').length
    if (failed > 0) {
      logger.warn(`${failed}/${styleModules.length} 个样式资源加载失败`)
    }

    return { 
      phase: InitPhase.STYLES, 
      success: failed === 0, 
      duration: performance.now() - startTime 
    }
  }
}

设计亮点：

  1. 结果收集：每个阶段的初始化结果都被记录，便于调试和监控

  2. 容错设计：

    • 核心插件失败 → 抛出错误，阻止启动
    • 样式加载失败 → 记录警告，继续启动
    • 功能初始化失败 → 记录警告，继续启动

  3. 重试机制：

private async retryImport<T>(
  importFn: () => Promise<T>,
  retries = 3,
  delay = 1000,
): Promise<T> {
  for (let i = 0; i <= retries; i++) {
    try {
      return await importFn()
    } catch (error) {
      if (i === retries) throw error
      await new Promise(resolve => setTimeout(resolve, delay * (i + 1)))
    }
  }
}

4.4 入口文件：清晰的启动流程

// src/main.ts

async function bootstrap() {
  const totalStartTime = performance.now()

  try {
    // 1. 初始化核心依赖（同步，阻塞）
    const app = initCore()

    // 2. 挂载应用（尽早显示界面）
    app.mount('#app')
    logger.info('✓ 应用已挂载到 DOM')

    // 3. 初始化插件系统（异步，不阻塞渲染）
    const initializer = new AppInitializer()
    await initializer.initPlugins(app)

    // 4. 加载样式资源（异步，不阻塞交互）
    initializer.loadStyles().catch((error) => {
      logger.warn('样式资源加载失败（不影响功能）', error)
    })

    // 5. 初始化非关键功能（异步，不阻塞交互）
    initializer.initFeatures(app, router).catch((error) => {
      logger.warn('非关键功能初始化失败（不影响核心功能）', error)
    })

    // 输出初始化摘要
    const summary = initializer.getSummary()
    logger.info('🎉 应用启动完成', summary)

    // 暴露调试工具（仅开发环境）
    if (import.meta.env.DEV) {
      window.__APP_INITIALIZER__ = initializer
      window.__PLUGIN_INSTALLER__ = initializer.pluginInstaller
    }
  } catch (error) {
    // 降级启动：只加载核心功能
    logger.warn('⚠️ 尝试降级启动（仅核心功能）')
    const app = initCore()
    app.mount('#app')
  }
}

五、性能优化：数据说话

5.1 性能测试方法

使用 Chrome DevTools Performance 和自定义性能监控进行测试：

// 性能监控代码
const startTime = performance.now()

// ... 执行操作

const duration = performance.now() - startTime
console.log(`操作耗时: ${duration.toFixed(2)}ms`)

测试环境：

  • CPU: Intel i7-10700K
  • 内存: 32GB
  • 浏览器: Chrome 120
  • 网络: Fast 3G（模拟真实网络环境）

5.2 性能对比数据

启动时间对比：

指标 旧架构 新架构 改进
核心依赖初始化 280ms 250ms ↓ 11%
插件系统初始化 300ms 180ms ↓ 40%
首次内容绘制（FCP） 850ms 600ms ↓ 29%
首次渲染（FMP） 1200ms 800ms ↓ 33%
可交互时间（TTI） 1500ms 980ms ↓ 35%

内存占用对比：

指标 旧架构 新架构 改进
初始堆内存 45MB 38MB ↓ 16%
插件系统内存 8MB 5MB ↓ 38%
运行时峰值内存 120MB 105MB ↓ 13%

代码体积对比：

模块 旧架构 新架构 改进
类型定义 150行 80行 ↓ 47%
插件管理器 425行 180行 ↓ 58%
注册中心 93行 45行 ↓ 52%
初始化逻辑 169行 390行 +131%
总计 837行 615行 ↓ 26.5%

注：初始化逻辑增加是因为职责分离，将原本混在 main.ts 中的逻辑提取到 app-initializer.ts。

5.3 性能提升的关键因素

1. 移除 EventEmitter 开销

// 旧架构：每次操作都触发事件
class PluginManager extends EventEmitter {
  async install(name: string) {
    this.emit('before:install', name)  // 遍历监听器
    await plugin.install(app)
    this.emit('after:install', name)   // 遍历监听器
  }
}

// 新架构：直接执行，无额外开销
class PluginInstaller {
  async installOne(app: App, name: string) {
    await plugin.install(app, options)
    this.installed.add(name)
  }
}

节省时间：每个插件节省 ~15ms，3 个插件共节省 ~45ms

2. 优化数据结构

// 旧架构：数组查找 O(n)
private plugins: PluginDefinition[] = []
private installed: string[] = []

isInstalled(name: string) {
  return this.installed.includes(name)  // O(n)
}

// 新架构：Map/Set 查找 O(1)
private plugins = new Map<string, PluginDefinition>()
private installed = new Set<string>()

isInstalled(name: string) {
  return this.installed.has(name)  // O(1)
}

节省时间：查找操作从 O(n) 降到 O(1)，大量调用时效果显著

3. 移除无用的依赖检查

// 旧架构：每次安装都检查依赖（实际没有依赖）
async install(name: string) {
  await this.checkDependencies(name)  // 遍历依赖树，耗时 ~45ms
  await plugin.install(app)
}

// 新架构：使用 priority 控制顺序，无需依赖检查
const sortedPlugins = plugins.sort(
  (a, b) => (a.metadata.priority ?? 100) - (b.metadata.priority ?? 100)
)

节省时间：移除依赖检查，节省 ~45ms

4. 分阶段异步加载

// 旧架构：所有资源串行加载，阻塞渲染
async function bootstrap() {
  await initCore()
  await initPlugins()
  await loadStyles()
  await initFeatures()
  app.mount('#app')  // 最后才挂载
}

// 新架构：尽早挂载，异步加载非关键资源
async function bootstrap() {
  const app = initCore()
  app.mount('#app')  // 尽早挂载，用户看到界面
  
  await initPlugins()  // 关键插件
  loadStyles()         // 异步，不阻塞
  initFeatures()       // 异步，不阻塞
}

用户体验提升：

  • 旧架构：用户等待 1500ms 才看到界面
  • 新架构：用户等待 800ms 就看到界面，提升 47%

六、迁移过程：渐进式重构

6.1 并行运行策略

为了降低风险，我采用了并行运行策略：

步骤 1：创建 V2 版本文件

src/plugins/
├── core/                    # 新架构
│   ├── types.ts
│   └── installer.ts
├── registry-v2.ts           # 新架构
├── PluginManager.ts         # 旧架构（保留）
├── types.ts                 # 旧架构（保留）
└── registry.ts              # 旧架构（保留）

src/
├── main.ts                  # 旧入口（保留）
├── main-v2.ts               # 新入口
└── bootstrap/
    └── app-initializer.ts   # 新架构

步骤 2：配置双入口

// vite.config.ts
export default defineConfig({
  server: { port: 5173 },  // 旧架构端口
  // ...
})

// vite.config.v2.ts
export default defineConfig({
  server: { port: 5174 },  // 新架构端口
  // ...
})

// package.json
{
  "scripts": {
    "dev": "vite",           // 旧架构
    "dev:v2": "vite --config vite.config.v2.ts"  // 新架构
  }
}

步骤 3：对比测试

# 终端 1：运行旧架构
npm run dev

# 终端 2：运行新架构
npm run dev:v2

# 对比测试：
# - 功能完整性
# - 性能指标
# - 错误率
# - 内存占用

测试清单：

  • 所有页面正常渲染
  • 路由跳转正常
  • 状态管理正常
  • 国际化切换正常
  • 错误处理正常
  • 性能指标达标
  • 无控制台错误

6.2 完全迁移

经过 2 周的并行测试，确认新架构稳定后，执行完全迁移：

步骤 1：备份旧文件

mkdir src/plugins/legacy
mv src/plugins/PluginManager.ts src/plugins/legacy/
mv src/plugins/types.ts src/plugins/legacy/
mv src/plugins/registry.ts src/plugins/legacy/
mv src/plugins/index.ts src/plugins/legacy/

步骤 2：重命名新文件

# 插件系统
mv src/plugins/registry-v2.ts src/plugins/registry.ts

# 入口文件
mv src/main.ts src/main-legacy.ts
mv src/main-v2.ts src/main.ts

# Vite 配置
mv vite.config.ts vite.config-legacy.ts
mv vite.config.v2.ts vite.config.ts

# HTML 入口
mv index.html index-legacy.html
mv index-v2.html index.html

步骤 3：更新配置

// vite.config.ts - 改回默认端口
export default defineConfig({
  server: { port: 5173 },  // 改回 5173
  // ...
})

// package.json - 保留回滚选项
{
  "scripts": {
    "dev": "vite",                              // 新架构（默认）
    "dev:legacy": "vite --config vite.config-legacy.ts"  // 旧架构（回滚）
  }
}

步骤 4：创建新的导出文件

// src/plugins/index.ts - 新的统一导出
export * from './core/types'
export * from './core/installer'
export * from './registry'

6.3 回滚方案

如果新架构出现问题，可以快速回滚：

# 方案 1：使用 legacy 脚本
npm run dev:legacy

# 方案 2：恢复旧文件（如果已删除）
cp src/plugins/legacy/* src/plugins/
cp src/main-legacy.ts src/main.ts
cp vite.config-legacy.ts vite.config.ts

七、踩坑与经验

7.1 踩过的坑

坑 1：过早优化

最初我想实现插件的懒加载、热重载等高级功能，但后来发现：

// ❌ 过度设计：实现了懒加载，但从未使用
class PluginManager {
  async lazyLoad(name: string) {
    const plugin = await import(`./plugins/${name}`)
    this.register(plugin.default)
  }
}

// ✅ 实际需求：所有插件都在启动时加载
const plugins = [
  piniaStateManagerPlugin,
  i18nSystemPlugin,
  consoleInterceptorPlugin,
]

教训：先实现核心功能，等真正需要时再优化。

坑 2：类型定义过于宽泛

// ❌ 旧架构：any 类型导致运行时错误
interface PluginDefinition {
  install: (app: App, options?: any) => void
}

// 使用时没有类型检查
pluginManager.install('pinia', { 
  enableDevtoolz: true  // 拼写错误，运行时才发现
})

// ✅ 新架构：强类型约束
interface PiniaOptions {
  enableDevtools: boolean  // 明确的类型
}

const piniaPlugin: PluginDefinition<PiniaOptions> = {
  install(app, options) {
    options.enableDevtoolz  // 编译时报错：属性不存在
  }
}

教训：充分利用 TypeScript 的类型系统，在编译时发现错误。

坑 3：忽略降级策略

最初的实现中，如果插件安装失败，整个应用就无法启动：

// ❌ 旧实现：插件失败导致应用崩溃
async function bootstrap() {
  await initPlugins()  // 失败则抛出错误
  app.mount('#app')    // 永远不会执行
}

// ✅ 新实现：降级启动
async function bootstrap() {
  try {
    const app = initCore()
    app.mount('#app')  // 先挂载，保证基本可用
    await initPlugins()
  } catch (error) {
    logger.warn('插件初始化失败，使用降级模式')
    // 应用仍然可用，只是缺少部分功能
  }
}

教训：关键系统必须有降级方案，保证核心功能可用。

坑 4：性能测试不充分

最初只在开发环境测试，生产环境发现性能问题：

// 问题：开发环境的日志输出影响性能
if (this.options.debug) {
  console.log('Installing plugin:', name)  // 开发环境
}

// 解决：使用专业的日志系统
logger.debug('Installing plugin:', name)  // 生产环境自动禁用

教训：在接近生产环境的条件下测试性能。

7.2 最佳实践总结

1. 遵循 YAGNI 原则

// ❌ 不要实现"可能会用到"的功能
class PluginManager {
  enable() { }    // 从未使用
  disable() { }   // 从未使用
  uninstall() { } // 从未使用
}

// ✅ 只实现当前需要的功能
class PluginInstaller {
  register() { }  // 需要
  install() { }   // 需要
}

2. 职责单一

// ❌ 一个类做太多事情
class PluginManager {
  register() { }      // 注册
  install() { }       // 安装
  checkDeps() { }     // 依赖检查
  emit() { }          // 事件管理
}

// ✅ 每个类只做一件事
class PluginInstaller { install() { } }
function getAllPlugins() { }
class AppInitializer { init() { } }

3. 类型安全优先

// ❌ 使用 any 类型
function install(options?: any) { }

// ✅ 使用泛型约束
function install<T>(options?: T) { }

// ✅✅ 更好：明确的类型定义
interface PluginDefinition<T = any> {
  install: (app: App, options?: T) => void
}

4. 性能监控

// 在关键路径添加性能监控
async function install(name: string) {
  const startTime = performance.now()
  
  await plugin.install(app)
  
  const duration = performance.now() - startTime
  logger.info(`Plugin ${name} installed in ${duration.toFixed(2)}ms`)
}

5. 错误处理分级

// 核心功能：失败则抛出错误
async initCore() {
  if (!app) throw new Error('Failed to create app')
}

// 非关键功能：失败则记录警告
async loadStyles() {
  try {
    await import('./styles.css')
  } catch (error) {
    logger.warn('Style loading failed', error)
    // 不抛出错误，应用继续运行
  }
}

6. 渐进式迁移

阶段 1: 创建 V2 版本（并行运行）
  ↓
阶段 2: 对比测试（2 周）
  ↓
阶段 3: 灰度发布（10% → 50% → 100%）
  ↓
阶段 4: 完全迁移
  ↓
阶段 5: 清理旧代码

7.3 调试技巧

1. 暴露调试工具到全局

// 开发环境暴露调试工具
if (import.meta.env.DEV) {
  window.__APP_INITIALIZER__ = initializer
  window.__PLUGIN_INSTALLER__ = initializer.pluginInstaller
}

// 在控制台调试
window.__PLUGIN_INSTALLER__.getInstalled()
// ['pinia', 'i18n', 'consoleInterceptor']

2. 详细的日志输出

// 使用结构化日志
logger.info('🎉 应用启动完成', {
  总耗时: `${totalDuration.toFixed(2)}ms`,
  初始化阶段: summary.phases,
  插件列表: installer.getInstalled(),
})

// 控制台输出：
// 🎉 应用启动完成
// {
//   总耗时: "980.23ms",
//   初始化阶段: [
//     { phase: "plugins", success: true, duration: 180.45 },
//     { phase: "styles", success: true, duration: 120.33 },
//     { phase: "features", success: true, duration: 95.12 }
//   ],
//   插件列表: ["pinia", "i18n", "consoleInterceptor"]
// }

3. Chrome DevTools Performance

使用 Performance 面板分析启动流程：

  1. 打开 DevTools → Performance
  2. 点击录制按钮
  3. 刷新页面
  4. 停止录制
  5. 分析火焰图，找出耗时操作

八、实际效果与收益

8.1 量化收益

开发体验提升：

  • 代码可读性：从 6/10 提升到 9/10（团队评分）
  • 调试效率：定位问题时间从 30 分钟降到 10 分钟
  • 新人上手时间：从 2 天降到 0.5 天

性能提升：

  • 首次渲染时间：1200ms → 800ms（↓ 33%）
  • 内存占用：45MB → 38MB（↓ 16%）
  • 代码体积：837 行 → 615 行（↓ 26.5%）

维护成本降低：

  • 单元测试覆盖率：从 45% 提升到 85%
  • Bug 修复时间：从平均 2 小时降到 0.5 小时
  • 代码审查时间：从 30 分钟降到 15 分钟

8.2 团队反馈

开发者 A：

"新架构太清晰了！我第一次看代码就能理解整个启动流程，不像以前要跳来跳去。"

开发者 B：

"类型提示太棒了！以前配置插件经常拼写错误，现在编译时就能发现。"

技术负责人：

"性能提升很明显，用户反馈页面加载速度快了很多。代码量减少也让维护更轻松。"

8.3 用户体验改善

加载速度对比（用户感知）：

网络环境 旧架构 新架构 改善
Fast 3G 2.5s 1.6s ↓ 36%
Slow 3G 4.8s 3.2s ↓ 33%
WiFi 0.9s 0.6s ↓ 33%

用户满意度（问卷调查，N=50）：

  • 加载速度满意度：72% → 91%
  • 页面响应速度：68% → 88%
  • 整体体验：75% → 90%

九、经验总结与建议

9.1 何时应该重构

重构信号：

  1. ✅ 代码使用率低于 50%（大量未使用的功能）
  2. ✅ 性能问题明显（启动时间 > 2s）
  3. ✅ 维护成本高（修改一个功能需要改多个文件）
  4. ✅ 新人上手困难（理解代码需要 > 1 天）
  5. ✅ 类型安全性差（大量 any 类型）

不应该重构的情况：

  1. ❌ 代码运行良好，只是"看起来不够优雅"
  2. ❌ 没有明确的性能问题
  3. ❌ 团队没有足够的测试覆盖
  4. ❌ 项目处于紧急交付期

9.2 重构的关键原则

1. YAGNI（You Aren't Gonna Need It）

不要实现"可能会用到"的功能，只实现当前需要的。

2. KISS（Keep It Simple, Stupid）

简单的解决方案往往是最好的。

3. 职责单一（Single Responsibility）

每个模块只做一件事，做好一件事。

4. 渐进式迁移（Progressive Migration）

不要一次性重写所有代码，采用并行运行、灰度发布的策略。

5. 数据驱动（Data-Driven）

用性能数据、使用率数据指导重构决策，不要凭感觉。

9.3 给其他开发者的建议

1. 先分析，再动手

分析阶段（1-2 天）：
├─ 统计代码使用率
├─ 分析性能瓶颈
├─ 识别设计问题
└─ 制定重构方案

实施阶段（1-2 周）：
├─ 创建 V2 版本
├─ 并行测试
├─ 灰度发布
└─ 完全迁移

2. 保持向后兼容

// 提供兼容层，让旧代码平滑迁移
export class PluginManager {
  // 标记为废弃，但仍然可用
  /** @deprecated 使用 PluginInstaller 替代 */
  async install(name: string) {
    console.warn('PluginManager.install is deprecated')
    return this.installer.installOne(app, name)
  }
}

3. 充分测试

// 测试覆盖关键路径
describe('PluginInstaller', () => {
  it('应该成功安装插件', async () => { })
  it('应该处理安装失败', async () => { })
  it('应该防止重复安装', async () => { })
  it('应该按优先级排序', async () => { })
  it('应该处理超时', async () => { })
})

4. 文档先行

在重构前写好文档：

  • 为什么要重构（问题分析）
  • 怎么重构（设计方案）
  • 如何迁移（迁移指南）
  • 如何回滚（应急方案）

5. 团队沟通

  • 重构前：与团队讨论方案，达成共识
  • 重构中：定期同步进度，及时调整
  • 重构后：分享经验，总结教训

9.4 常见陷阱

陷阱 1：完美主义

// ❌ 追求完美，永远无法完成
class PluginInstaller {
  // 实现了 20 个方法，但只用到 3 个
}

// ✅ 先实现核心功能，后续迭代
class PluginInstaller {
  register() { }
  install() { }
  // 其他功能等需要时再加
}

陷阱 2：过度抽象

// ❌ 过度抽象，增加复杂度
abstract class BaseInstaller<T> {
  abstract install(item: T): void
}
class PluginInstaller extends BaseInstaller<Plugin> { }
class ModuleInstaller extends BaseInstaller<Module> { }

// ✅ 简单直接
class PluginInstaller {
  install(plugin: Plugin) { }
}

陷阱 3：忽略边界情况

// ❌ 只考虑正常流程
async install(name: string) {
  const plugin = this.plugins.get(name)
  await plugin.install(app)
}

// ✅ 处理边界情况
async install(name: string) {
  // 1. 插件不存在
  if (!this.plugins.has(name)) {
    throw new Error(`Plugin ${name} not found`)
  }
  
  // 2. 已经安装
  if (this.installed.has(name)) {
    return
  }
  
  // 3. 安装超时
  await Promise.race([
    plugin.install(app),
    timeout(10000)
  ])
}

陷阱 4：缺少监控

// ❌ 没有性能监控
async install(name: string) {
  await plugin.install(app)
}

// ✅ 添加性能监控
async install(name: string) {
  const startTime = performance.now()
  await plugin.install(app)
  const duration = performance.now() - startTime
  
  // 记录性能数据
  logger.info(`Plugin ${name} installed in ${duration}ms`)
  
  // 性能告警
  if (duration > 1000) {
    logger.warn(`Plugin ${name} installation is slow`)
  }
}

十、总结与展望

10.1 核心收获

这次重构让我深刻体会到：

  1. YAGNI 原则的威力：删除 80% 的未使用代码，性能提升 35%
  2. 职责分离的重要性：清晰的模块划分让代码易于理解和维护
  3. 类型安全的价值：TypeScript 的强类型约束在编译时就能发现大量错误
  4. 渐进式迁移的必要性：并行运行、灰度发布大大降低了风险
  5. 性能监控的关键性：数据驱动的优化比凭感觉更有效

10.2 架构对比总结

维度 旧架构 新架构 改进
代码行数 837 行 615 行 ↓ 26.5%
启动时间 1500ms 980ms ↓ 35%
内存占用 45MB 38MB ↓ 16%
类型安全 大量 any 强类型 ✅
可维护性 6/10 9/10 ↑ 50%
测试覆盖率 45% 85% ↑ 89%

10.3 未来优化方向

虽然新架构已经很好，但仍有优化空间：

1. 插件预加载

// 在空闲时预加载非关键插件
if ('requestIdleCallback' in window) {
  requestIdleCallback(() => {
    import('./plugins/analytics')
    import('./plugins/monitoring')
  })
}

2. 插件懒加载

// 按需加载插件
const lazyPlugins = {
  analytics: () => import('./plugins/analytics'),
  monitoring: () => import('./plugins/monitoring'),
}

// 用户触发某个功能时才加载对应插件
async function enableAnalytics() {
  const plugin = await lazyPlugins.analytics()
  installer.register(plugin.default)
  await installer.installOne(app, 'analytics')
}

3. 性能预算

// 设置性能预算，超出则告警
const PERFORMANCE_BUDGET = {
  pluginInstall: 200,  // 单个插件安装不超过 200ms
  totalStartup: 1000,  // 总启动时间不超过 1000ms
}

if (duration > PERFORMANCE_BUDGET.pluginInstall) {
  logger.error(`Performance budget exceeded: ${name} took ${duration}ms`)
}

4. 插件依赖管理

// 如果未来真的需要依赖管理，可以这样实现
interface PluginMetadata {
  name: string
  version: string
  dependencies?: string[]  // 依赖的插件名称
}

// 拓扑排序，确保依赖顺序
function sortPluginsByDependencies(plugins: PluginDefinition[]) {
  // 实现拓扑排序算法
}

10.4 写在最后

这次重构历时 3 周，从问题分析到完全迁移，每一步都很谨慎。最终的结果证明，简单的设计往往是最好的设计。

如果你的项目也面临类似问题，希望这篇文章能给你一些启发。记住：

  • 🎯 先分析问题，再动手重构
  • 🧹 删除不需要的代码，比添加新功能更重要
  • 🔒 类型安全能在编译时发现大量错误
  • 🚀 性能优化要基于数据，不要凭感觉
  • 🛡️ 渐进式迁移能大大降低风险

最后，感谢团队成员的支持和配合，感谢用户的耐心等待。希望这次重构的经验能帮助到更多开发者！

附录：完整代码示例

A. 插件定义示例

// src/plugins/my-plugin.ts
import type { PluginDefinition } from './core/types'

export interface MyPluginOptions {
  apiKey: string
  timeout?: number
  debug?: boolean
}

const myPlugin: PluginDefinition<MyPluginOptions> = {
  metadata: {
    name: 'myPlugin',
    version: '1.0.0',
    description: '我的自定义插件',
    core: false,
    priority: 50,
  },
  defaultOptions: {
    timeout: 5000,
    debug: false,
  },
  async install(app, options) {
    // 验证配置
    if (!options.apiKey) {
      throw new Error('API key is required')
    }

    // 初始化插件
    const api = createAPI(options)
    
    // 注入到 Vue 应用
    app.provide('myPlugin', api)
    
    // 添加全局属性
    app.config.globalProperties.$myPlugin = api
    
    if (options.debug) {
      console.log('MyPlugin initialized with options:', options)
    }
  },
}

export default myPlugin

B. 使用插件示例

// 在组件中使用插件
<script setup lang="ts">
import { inject } from 'vue'
import type { MyPluginAPI } from '@/plugins/my-plugin'

// 方式 1：使用 inject
const myPlugin = inject<MyPluginAPI>('myPlugin')

// 方式 2：使用全局属性
import { getCurrentInstance } from 'vue'
const instance = getCurrentInstance()
const myPlugin = instance?.appContext.config.globalProperties.$myPlugin

// 使用插件功能
async function fetchData() {
  const data = await myPlugin?.fetch('/api/data')
  console.log(data)
}
</script>

C. 测试示例

// src/plugins/core/installer.test.ts
import { describe, it, expect, beforeEach } from 'vitest'
import { createApp } from 'vue'
import { PluginInstaller } from './installer'
import type { PluginDefinition } from './types'

describe('PluginInstaller', () => {
  let installer: PluginInstaller
  let app: ReturnType<typeof createApp>

  beforeEach(() => {
    installer = new PluginInstaller({ debug: false })
    app = createApp({})
  })

  it('应该成功注册插件', () => {
    const plugin: PluginDefinition = {
      metadata: { name: 'test', version: '1.0.0' },
      install: () => {},
    }

    installer.register(plugin)
    expect(installer['plugins'].has('test')).toBe(true)
  })

  it('应该成功安装插件', async () => {
    let installed = false
    const plugin: PluginDefinition = {
      metadata: { name: 'test', version: '1.0.0' },
      install: () => { installed = true },
    }

    installer.register(plugin)
    const result = await installer.installOne(app, 'test')

    expect(result.success).toBe(true)
    expect(installed).toBe(true)
    expect(installer.isInstalled('test')).toBe(true)
  })

  it('应该处理安装失败', async () => {
    const plugin: PluginDefinition = {
      metadata: { name: 'test', version: '1.0.0' },
      install: () => { throw new Error('Install failed') },
    }

    installer.register(plugin)
    const result = await installer.installOne(app, 'test')

    expect(result.success).toBe(false)
    expect(result.error?.message).toBe('Install failed')
  })

  it('应该防止重复安装', async () => {
    let installCount = 0
    const plugin: PluginDefinition = {
      metadata: { name: 'test', version: '1.0.0' },
      install: () => { installCount++ },
    }

    installer.register(plugin)
    await installer.installOne(app, 'test')
    await installer.installOne(app, 'test')

    expect(installCount).toBe(1)
  })
})

相关资源：

如果这篇文章对你有帮助，欢迎点赞、收藏、分享！有任何问题也欢迎在评论区讨论。

昨天以前首页

CSS 全局样式污染问题复盘

✇掘金 前端
作者 大象的鼻子那么长
2025年12月25日 10:22

一、问题现象

1.1 问题描述

VGM 编辑弹窗（使用 CmcDialog 组件）出现异常的内边距，导致弹窗内容布局错乱，表单元素间距过大。

1.2 问题截图

弹窗内容区域出现了不应有的 padding: 52px 50px 样式，导致：

  • 表单内容被压缩
  • 布局与设计稿不符
  • 视觉效果异常

1.3 影响范围

所有使用 el-dialog 或基于 el-dialog 封装的组件（如 CmcDialog）都受到影响。

二、问题定位

2.1 排查过程

  1. 检查组件自身样式 - CmcDialog 组件样式正常
  2. 检查父组件样式 - 使用 CmcDialog 的页面无异常样式
  3. 使用 DevTools 检查 - 发现 .el-dialog 被注入了全局样式
  4. 全局搜索污染源 - 搜索 padding: 52px 50px 定位到问题文件

2.2 问题根源

在 src/views/search_service/ship-schedules/components/Subscribe.vue 中发现以下代码：

<style scoped lang="scss">
.subscriber-dialog {
  :global(.el-dialog) {
    padding: 52px 50px;
  }
}
</style>

2.3 为什么会造成全局污染？

这里涉及到 Vue Scoped CSS 和 :global() 的工作原理：

Vue Scoped CSS 原理

<!-- 编译前 -->
<style scoped>
  .subscriber-dialog {
    color: red;
  }
</style>

<!-- 编译后 -->
<style>
  .subscriber-dialog[data-v-xxxxx] {
    color: red;
  }
</style>

Vue 会为 scoped 样式添加唯一的 data-v-xxxxx 属性选择器，确保样式只作用于当前组件。

:global() 的作用

:global() 是 CSS Modules 和 Vue 的一个特性，用于跳过 scoped 限制，生成全局样式：

// 编译前
.subscriber-dialog {
  :global(.el-dialog) {
    padding: 52px 50px;
  }
}

// 编译后（注意：.el-dialog 没有 data-v 属性！）
.subscriber-dialog[data-v-xxxxx] .el-dialog {
  padding: 52px 50px;
}

关键问题：el-dialog 的 DOM 结构

Element Plus 的 el-dialog 默认会通过 append-to-body 将 DOM 挂载到 <body> 下：

<body>
  <!-- 页面内容 -->
  <div id="app">
    <div class="subscriber-dialog" data-v-xxxxx>
      <!-- 触发按钮 -->
    </div>
  </div>

  <!-- Dialog 被 teleport 到 body 下 -->
  <div class="el-overlay subscriber-dialog">
    <!-- modal-class 应用在这里 -->
    <div class="el-dialog">
      <!-- 实际的 dialog -->
      ...
    </div>
  </div>
</body>

由于 modal-class="subscriber-dialog" 应用到了 el-overlay 上，而 .el-dialog 是其子元素，所以选择器 .subscriber-dialog .el-dialog 能够匹配到！

但问题在于：:global(.el-dialog) 生成的样式没有足够的特异性限制，当其他页面的 dialog 也被挂载到 body 时，如果 CSS 加载顺序导致这个样式后加载，就会覆盖其他 dialog 的样式。

三、深度原理剖析

3.1 CSS 特异性（Specificity）

CSS 特异性决定了当多个规则应用于同一元素时，哪个规则优先：

选择器类型 特异性值
内联样式 1000
ID 选择器 100
类/属性/伪类 10
元素/伪元素 1 
// 特异性：20（两个类选择器）
.subscriber-dialog .el-dialog {
  padding: 52px 50px;
}

// 特异性：20（两个类选择器）
.cmc-dialog.el-dialog {
  padding: 0;
}

当特异性相同时，后加载的样式会覆盖先加载的样式。

3.2 样式加载顺序问题

在 SPA 应用中，组件样式是按需加载的：

1. 用户访问首页 → 加载首页组件样式
2. 用户访问船期页面 → 加载 Subscribe.vue 样式（包含全局污染）
3. 用户访问 VGM 页面 → CmcDialog 样式被污染样式覆盖

3.3 Teleport/Portal 的影响

Element Plus Dialog 使用 Vue 3 的 Teleport 特性：

<Teleport to="body">
  <div class="el-overlay">
    <div class="el-dialog">...</div>
  </div>
</Teleport>

这导致：

  1. Dialog DOM 脱离了组件的 DOM 树
  2. Scoped 样式的 data-v-xxxxx 属性无法正确应用
  3. 必须使用 :global() 或 :deep() 才能样式化 dialog

四、修复方案

4.1 修复污染源（治本）

修改前（错误写法）：

<el-dialog modal-class="subscriber-dialog">
  ...
</el-dialog>

<style scoped lang="scss">
.subscriber-dialog {
  :global(.el-dialog) {
    padding: 52px 50px;
  }
}
</style>

修改后（正确写法）：

<el-dialog class="subscriber-dialog-box" modal-class="subscriber-dialog">
  ...
</el-dialog>

<style scoped lang="scss">
// 使用 class 属性直接应用到 el-dialog 上
// 组合选择器确保只影响特定的 dialog
:global(.subscriber-dialog-box) {
  padding: 52px 50px;

  .el-dialog__header {
    display: none;
  }
}
</style>

关键改动：

  1. 使用 class 而非仅依赖 modal-class
  2. 使用组合选择器 .subscriber-dialog-box 确保唯一性
  3. 样式只作用于带有该特定类名的 dialog

4.2 加固组件库（治标 + 防御）

在 CmcDialog 组件中添加高优先级样式重置：

.cmc-dialog {
  &.el-dialog {
    // 使用 !important 确保不被外部样式覆盖
    padding: 0 !important;
    padding-top: 0 !important;
    padding-bottom: 0 !important;
    padding-left: 0 !important;
    padding-right: 0 !important;
  }

  .el-dialog__header {
    padding: 0 !important;
    margin: 0 !important;
  }

  .el-dialog__body {
    padding: 0 !important;
  }

  .el-dialog__footer {
    padding: 0 !important;
    margin: 0 !important;
  }
}

五、同类问题预防指南

5.1 ❌ 错误写法示例

// 错误1：直接使用 :global 修改 Element Plus 组件
:global(.el-dialog) { ... }
:global(.el-table) { ... }
:global(.el-form) { ... }

// 错误2：在 scoped 样式中使用过于宽泛的选择器
.my-page {
  :global(.el-button) {
    background: red;
  }
}

// 错误3：在全局样式文件中直接修改组件样式
// src/assets/styles/index.scss
.el-dialog {
  padding: 52px 50px;
}

5.2 ✅ 正确写法示例

// 正确1：使用组合选择器，确保唯一性
:global(.my-specific-dialog.el-dialog) {
  padding: 52px 50px;
}

// 正确2：使用 BEM 命名 + 组合选择器
:global(.page-name__dialog.el-dialog) {
  // 样式
}

// 正确3：在组件上使用 class 属性
<el-dialog class="my-unique-dialog">

// 正确4：使用 CSS 变量进行定制
.my-dialog {
  --el-dialog-padding-primary: 52px 50px;
}

5.3 代码审查检查清单

在 Code Review 时，检查以下内容：

  • 是否使用了 :global(.el-xxx) 直接修改 Element Plus 组件？
  • 全局样式文件中是否有直接修改组件库样式的代码？
  • 使用 :global() 时是否添加了足够特异性的父选择器？
  • Dialog/Drawer 等 Teleport 组件是否使用了 class 属性？
  • 样式是否可能影响其他页面的同类组件？

5.4 ESLint/Stylelint 规则建议

可以配置 Stylelint 规则来检测潜在的全局污染：

// stylelint.config.js
module.exports = {
  rules: {
    // 禁止直接使用 Element Plus 类名作为选择器
    'selector-disallowed-list': [
      '/^\\.el-(?!.*\\.)/', // 匹配单独的 .el-xxx 选择器
      {
        message: '请使用组合选择器避免全局污染，如 .my-class.el-dialog'
      }
    ]
  }
}

六、总结

6.1 问题本质

这是一个典型的 CSS 作用域泄漏 问题，由以下因素共同导致：

  1. Teleport 机制 - Dialog DOM 脱离组件树
  2. :global() 滥用 - 跳过 scoped 限制
  3. 选择器特异性不足 - 没有使用组合选择器
  4. 样式加载顺序 - 后加载的样式覆盖先加载的

6.2 核心教训

  1. 永远不要直接 :global(.el-xxx) - 必须添加特定的父选择器或组合选择器
  2. 组件库封装要有防御性 - 使用 !important 重置关键样式
  3. 使用 class 而非仅 modal-class - 确保样式能正确应用
  4. 命名要有唯一性 - 使用 BEM 或页面前缀避免冲突

6.3 推荐的 Dialog 样式定制模式

<template>
  <el-dialog
    class="feature-name__dialog"
    modal-class="feature-name__overlay"
  >
    ...
  </el-dialog>
</template>

<style scoped lang="scss">
// 使用组合选择器，确保只影响当前组件的 dialog
:global(.feature-name__dialog.el-dialog) {
  // 自定义样式
}
</style>

七、相关资源

❌
❌