文件处理钩子的使用

文件处理钩子的使用

Vite.js 提供了丰富的钩子函数，其中文件处理钩子允许开发者在构建过程中拦截和修改文件内容。这些钩子在处理特殊文件格式、自定义转换逻辑或注入代码时特别有用。

transform 钩子基础用法

transform 是最常用的文件处理钩子，它接收文件内容和文件路径作为参数，返回修改后的内容：

// vite.config.js
export default {
  plugins: [
    {
      name: 'my-transform-plugin',
      transform(code, id) {
        if (id.endsWith('.custom')) {
          return `// 注入头部注释\n${code}`
        }
      }
    }
  ]
}

这个例子展示了如何为 .custom 后缀的文件添加注释。id 参数包含文件的完整路径，code 是文件原始内容。

处理特定文件类型

结合文件扩展名过滤可以精确控制钩子的作用范围：

export default {
  plugins: [
    {
      name: 'svg-transform',
      transform(code, id) {
        if (id.endsWith('.svg')) {
          // 将SVG转换为组件
          return `export default \`${code}\``
        }
      }
    }
  ]
}

异步文件处理

当需要进行异步操作时（如调用API或读取文件），transform 可以返回 Promise：

export default {
  plugins: [
    {
      name: 'async-transform',
      async transform(code, id) {
        if (id.includes('config.json')) {
          const remoteData = await fetch('https://api.example.com/config')
          return JSON.stringify({
            ...JSON.parse(code),
            ...await remoteData.json()
          })
        }
      }
    }
  ]
}

源码映射处理

处理文件时保持正确的源码映射对于调试很重要：

export default {
  plugins: [
    {
      name: 'transform-with-sourcemap',
      transform(code, id) {
        if (id.endsWith('.ts')) {
          return {
            code: code.replace(/console\.log\(.*\);/g, ''),
            map: null // 保留原始sourcemap
          }
        }
      }
    }
  ]
}

load 钩子的使用

load 钩子在文件被读取时触发，可以用于虚拟文件或自定义文件加载：

export default {
  plugins: [
    {
      name: 'virtual-module',
      load(id) {
        if (id === 'virtual:config') {
          return `export const config = ${JSON.stringify({
            version: '1.0.0',
            env: process.env.NODE_ENV
          })}`
        }
      }
    }
  ]
}

修改已有文件内容

结合 transform 和 load 可以实现复杂的内容修改：

export default {
  plugins: [
    {
      name: 'content-modifier',
      transform(code, id) {
        if (id.endsWith('.vue')) {
          // 在Vue文件中注入mixin
          return code.replace(
            '<script>',
            '<script>\nimport validationMixin from "@/mixins/validation"'
          )
        }
      }
    }
  ]
}

处理CSS文件

Vite 允许通过钩子自定义CSS处理：

export default {
  plugins: [
    {
      name: 'css-modifier',
      transform(code, id) {
        if (id.endsWith('.css')) {
          // 为所有CSS规则添加前缀
          return code.replace(
            /([^{]+\{)/g, 
            '[data-theme="dark"] $1'
          )
        }
      }
    }
  ]
}

构建阶段钩子

除了转换内容，还可以使用构建阶段钩子处理文件：

export default {
  plugins: [
    {
      name: 'build-optimizer',
      buildStart() {
        console.log('构建开始')
      },
      buildEnd() {
        console.log('构建结束')
      },
      generateBundle(options, bundle) {
        // 修改最终生成的包
        for (const fileName in bundle) {
          if (fileName.endsWith('.js')) {
            const chunk = bundle[fileName]
            chunk.code = `/* 构建时间: ${new Date().toISOString()} */\n${chunk.code}`
          }
        }
      }
    }
  ]
}

实际应用案例

实现一个自动国际化注入的插件：

export default {
  plugins: [
    {
      name: 'i18n-injector',
      async transform(code, id) {
        if (id.endsWith('.vue') || id.endsWith('.jsx')) {
          const i18nKeys = extractText(code) // 提取需要国际化的文本
          const translations = await loadTranslations(i18nKeys)
          
          return code.replace(
            /(['"`])(.*?)\1/g,
            (match, quote, text) => {
              return translations[text] 
                ? `$t('${translations[text]}')`
                : match
            }
          )
        }
      }
    }
  ]
}

function extractText(code) {
  // 实现文本提取逻辑
  return [...new Set(code.match(/['"`](.*?)['"`]/g).map(m => m.slice(1, -1)))]
}

async function loadTranslations(keys) {
  // 实现翻译加载逻辑
  const res = await fetch('/api/translate', {
    method: 'POST',
    body: JSON.stringify(keys)
  })
  return res.json()
}

性能优化考虑

频繁的文件处理可能影响构建速度，可以通过缓存优化：

const cache = new Map()

export default {
  plugins: [
    {
      name: 'cached-transform',
      transform(code, id) {
        if (!id.endsWith('.md')) return
        
        const cacheKey = createHash(code)
        if (cache.has(cacheKey)) {
          return cache.get(cacheKey)
        }
        
        const result = markdownToHtml(code)
        cache.set(cacheKey, result)
        return result
      }
    }
  ]
}

错误处理机制

健壮的文件处理插件需要包含错误处理：

export default {
  plugins: [
    {
      name: 'error-handling-transform',
      transform(code, id) {
        try {
          if (id.endsWith('.critical')) {
            return processCritical(code)
          }
        } catch (err) {
          this.error(`处理文件 ${id} 时出错: ${err.message}`)
          // 或者返回原始内容保证构建继续
          return code
        }
      }
    }
  ]
}

与其他插件交互

通过 this 上下文可以访问其他插件的方法：

export default {
  plugins: [
    {
      name: 'plugin-communicator',
      async buildStart() {
        // 等待某个插件完成初始化
        await this.resolve('vite:vue')
      },
      transform(code, id) {
        // 检查文件是否已被其他插件处理
        const meta = this.getModuleInfo(id)
        if (meta?.importers) {
          // 根据导入关系调整内容
        }
      }
    }
  ]
}

高级文件处理模式

对于需要多步骤处理的复杂场景，可以组合多个钩子：

export default {
  plugins: [
    {
      name: 'multi-stage-processor',
      // 第一阶段：标记需要处理的文件
      transform(code, id) {
        if (shouldProcess(id)) {
          return `// PROCESS-MARKER\n${code}`
        }
      },
      // 第二阶段：处理标记过的文件
      transform(code, id) {
        if (code.includes('// PROCESS-MARKER')) {
          return processMarkedFiles(code.replace('// PROCESS-MARKER\n', ''))
        }
      }
    }
  ]
}