@tanzerfe/plugins-vite

v0.0.7

Published

2 months ago

A collection of Vite plugins for environment configuration and utility enhancements

0High
0Medium
0Low

vite plugin environment configuration build-tools

@tanzerfe/plugins-vite

一个用于现代 Web 开发的实用 Vite 插件集合。

📦 安装

pnpm add @tanzerfe/plugins-vite -D

🔧 插件

1. 环境配置插件 (`envConfigPlugin`)

智能管理环境特定配置文件，支持开发模式和构建模式。

功能特性

开发模式：开发服务器启动时智能选择配置文件
构建模式：构建完成后处理 dist 目录配置
智能复制：同名文件自动跳过，避免冗余操作
模式映射：自动处理 Vite 默认模式（development → dev）
多配置输出：支持一次构建输出多个环境配置文件

使用方法

import { envConfigPlugin } from '@tanzerfe/plugins-vite'

export default defineConfig({
  plugins: [
    envConfigPlugin({
      configDir: 'public/com',
      outputDir: 'dist/com',
      outputFileName: 'config.js',
      enableLog: true    // 启用日志（默认）
    })
  ]
})

配置项

| 选项 | 类型 | 默认值 | 描述 | |------|------|---------|-------------| | configDir | string | 'public/com' | 包含环境配置文件的目录 | | outputDir | string | 'dist/com' | 配置文件的输出目录 | | outputFileName | string | 'config.js' | 输出配置文件的名称 | | obfuscate | boolean | false | 是否启用代码混淆 | | obfuscatorOptions | object | undefined | 自定义混淆配置（可选） | | enableLog | boolean | true | 是否启用日志输出 | | injectGisResources | boolean | false | 是否启用 GIS 资源注入到 index.html | | buildModes | string[] | Record<string, string[]> | undefined | 构建时要输出的配置文件模式列表 | | validateConfigKeys | boolean | false | 是否启用配置文件 key 一致性检查 |

使用方式

开发模式：

pnpm dev                  # 使用默认 config.js（如果存在）
pnpm dev --mode dev       # 使用 config-dev.js → config.js
pnpm dev --mode beta      # 使用 config-beta.js → config.js
pnpm dev --mode release   # 使用 config-release.js → config.js

构建模式：

pnpm build --mode dev     # 使用 config-dev.js → dist/com/config.js
pnpm build --mode beta    # 使用 config-beta.js → dist/com/config.js
pnpm build --mode release # 使用 config-release.js → dist/com/config.js

配置文件结构

public/com/
├── config.js           # 默认配置（不指定模式时使用）
├── config-dev.js       # 开发环境配置
├── config-beta.js      # 测试环境配置
└── config-release.js   # 生产环境配置

开发模式工作流

开发服务器启动时触发
根据模式选择对应配置文件
智能复制到 public/com/config.js
同名文件自动跳过复制

构建模式工作流

构建完成后触发
将对应配置文件复制到 dist/com/config.js
清理其他环境配置文件
可选：启用代码混淆

代码混淆

启用混淆：

envConfigPlugin({
  obfuscate: true // 使用默认混淆配置
})

自定义混淆配置：

envConfigPlugin({
  obfuscate: true,
  obfuscatorOptions: {
    compact: false
  }
})

GIS 资源注入

自动从 config.js 读取 window.$SYS_CFG.gisPkgCSS 和 window.$SYS_CFG.gisPkgJS 配置，并将这些资源注入到 index.html 的 <head> 中。

启用 GIS 资源注入：

envConfigPlugin({
  injectGisResources: true
})

config.js 配置示例：

window.$SYS_CFG = {
  // 支持字符串
  gisPkgCSS: 'https://example.com/gis.css',
  gisPkgJS: 'https://example.com/gis.js',
  
  // 也支持数组
  // gisPkgCSS: ['https://example.com/gis1.css', 'https://example.com/gis2.css'],
  // gisPkgJS: ['https://example.com/gis1.js', 'https://example.com/gis2.js'],
};

功能特性：

自动注入 CSS 和 JS 资源到 <head> 标签
资源位置在其他 script 之前
兼容字符串和数组两种数据类型
开发和构建模式都支持

多配置文件输出

通过 buildModes 配置选项，可以在一次构建中输出多个环境的配置文件。

所有环境输出相同配置：

envConfigPlugin({
  buildModes: ['dev', 'beta', 'prod']  // 输出这三个配置文件
})

执行任意构建命令，都会输出：

dist/com/config.js（当前 mode 的配置）
dist/com/config-dev.js
dist/com/config-beta.js
dist/com/config-prod.js

不同环境输出不同配置：

envConfigPlugin({
  buildModes: {
    dev: undefined,        // dev 环境只输出当前配置
    beta: ['beta*'],      // beta 环境输出所有以 beta 开头的配置
    prod: ['*']            // prod 环境输出所有配置
  }
})

| 构建命令 | 输出文件 | |---------|----------| | pnpm build:dev | config.js | | pnpm build:beta | config.js, config-beta.js, config-beta-test.js, ... | | pnpm build:prod | config.js, config-dev.js, config-beta.js, config-prod.js, ... |

通配符支持：

'*' - 匹配所有配置文件
'beta*' - 匹配所有以 beta 开头的配置（如 beta, beta-test, beta-staging）
'*test*' - 匹配所有包含 test 的配置
'dev' - 精确匹配 dev 配置

使用场景：

开发环境不需要多配置，生产环境需要：

buildModes: {
  dev: undefined,      // 开发时只输出 config.js
  prod: ['*']          // 生产环境输出所有配置
}

只有特定环境需要输出多配置：

buildModes: {
  beta: ['dev', 'beta', 'prod']  // 只有 beta 环境输出多个配置
}

配置文件 Key 一致性检查

在多环境配置场景下，确保所有配置文件具有相同的 key 结构非常重要。启用此功能后，插件会在构建前扫描所有配置文件并验证 key 的一致性。

启用检查：

envConfigPlugin({
  validateConfigKeys: true  // 启用 key 一致性检查
})

工作原理：

在构建开始时扫描 configDir 下所有 config-*.js 文件
提取每个文件的 window.$SYS_CFG 的 keys
对比所有文件的 keys 是否完全一致
如果发现不一致，显示详细差异并停止构建

示例输出（发现不一致时）：

配置文件 key 不一致！

  ❌ config-dev.js 缺少以下 keys: productionUrl, cdnUrl
  ❌ config-beta.js 缺少以下 keys: cdnUrl

请确保所有配置文件具有相同的 key 结构。

使用场景：

多环境配置管理，防止配置遗漏
团队协作时确保配置规范统一
CI/CD 流程中的配置验证

注意：此功能默认关闭，需要手动启用。建议在有多个配置文件的项目中启用。

2. 版本信息注入插件 (`injectVersionInfoPlugin`)

将版本号和构建时间注入到配置文件中。

重要提示：此插件必须与 envConfigPlugin 配合使用，且必须放在 envConfigPlugin 之前。

工作原理

injectVersionInfoPlugin 在构建开始时收集版本信息（版本号和构建时间）
将版本信息存储到插件对象中
envConfigPlugin 在处理配置文件时自动读取并注入版本信息
如果启用混淆，版本信息会在混淆前注入

使用方法

import { envConfigPlugin, injectVersionInfoPlugin } from '@tanzerfe/plugins-vite'

export default defineConfig({
  plugins: [
    // inject-version 必须在 env-config 之前
    injectVersionInfoPlugin({
      version: '1.0.0',  // 可选，不指定则使用环境变量 XF_VER
      enableLog: true
    }),
    envConfigPlugin({
      configDir: 'public/com',
      outputDir: 'dist/com',
      obfuscate: true  // 混淆会在 version 注入后进行
    })
  ]
})

配置项

| 选项 | 类型 | 默认值 | 描述 | |--------|------|---------|-------------| | version | string | process.env.XF_VER | 自定义版本号 | | enableLog | boolean | false | 是否启用日志输出 |

注入的版本信息

配置文件中会添加 window.$SYS_CFG.version 字段，包含以下信息：

window.$SYS_CFG = {
  // ... 其他配置
  version: {
    version: "1.0.0",                    // 版本号
    buildTime: "2024-12-24 10:00:00"     // 构建时间
  }
};

注意：Git 信息（分支、提交ID、用户等）由 envConfigPlugin 通过 Meta 字段注入到配置文件顶部的注释中。

3. Manifest 生成插件 (`manifestPlugin`)

生成一个带有预加载资源的 manifest 文件，以优化加载。

使用方法

import { manifestPlugin } from '@tanzerfe/plugins-vite'

export default defineConfig({
  plugins: [
    manifestPlugin({
      output: 'dist',
      filename: 'manifest.json',
      preload: ['main.js', 'vendor.js'],
      exclude: ['*.map', 'chunk-vendor-*.js'],
      enableLog: true
    })
  ]
})

配置项

| 选项 | 类型 | 默认值 | 描述 | |------|------|---------|-------------| | output | string | 'dist' | manifest 文件的输出目录 | | filename | string | 'manifest.json' | manifest 文件的名称 | | preload | string[] | [] | 要预加载的额外资源 | | exclude | string[] | [] | 要从预加载中排除的资源 | | enableLog | boolean | false | 启用详细日志 |

🚀 快速开始

基本设置

// vite.config.ts
import { defineConfig } from 'vite'
import { 
  envConfigPlugin, 
  injectVersionInfoPlugin, 
  manifestPlugin 
} from '@tanzerfe/plugins-vite'

export default defineConfig({
  plugins: [
    injectVersionInfoPlugin(),  // 必须在 envConfigPlugin 之前
    envConfigPlugin(),
    manifestPlugin()
  ]
})

高级配置

// vite.config.ts
import { defineConfig } from 'vite'
import { 
  envConfigPlugin, 
  injectVersionInfoPlugin, 
  manifestPlugin 
} from '@tanzerfe/plugins-vite'

export default defineConfig({
  plugins: [
    // inject-version 必须在 env-config 之前
    injectVersionInfoPlugin({
      enableLog: false
    }),
    envConfigPlugin({
      configDir: 'config',
      outputDir: 'dist/com',
      outputFileName: 'config.js',
      obfuscate: true,
      enableLog: false, // 关闭日志输出（生产环境建议关闭）
      obfuscatorOptions: {
        compact: true,
        stringArrayEncoding: ['base64'],
        identifierNamesGenerator: 'hexadecimal'
      }
    }),
    manifestPlugin({
      output: 'dist',
      filename: 'preload-manifest.json',
      exclude: ['*.map', 'chunk-vendor-*.js'],
      enableLog: true
    })
  ]
})

📁 文件结构

project/
├── config/
│   ├── config-dev.js
│   ├── config-beta.js
│   └── config-release.js
├── dist/
│   ├── com/
│   │   └── config.js
│   └── manifest.json
└── vite.config.ts

🔍 环境变量

XF_VER: 用于版本信息注入的版本号（由 injectVersionInfoPlugin 使用）

🛠️ 开发

构建

pnpm run build

监听模式

pnpm run dev

代码检查

pnpm run lint

📄 许可证

MIT 许可证 - 详情请见 LICENSE 文件。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tanzerfe/plugins-vite

📦 安装

🔧 插件

1. 环境配置插件 (envConfigPlugin)

功能特性

使用方法

配置项

使用方式

配置文件结构

开发模式工作流

构建模式工作流

代码混淆

GIS 资源注入

多配置文件输出

配置文件 Key 一致性检查

2. 版本信息注入插件 (injectVersionInfoPlugin)

工作原理

使用方法

配置项

注入的版本信息

3. Manifest 生成插件 (manifestPlugin)

使用方法

配置项

🚀 快速开始

基本设置

高级配置

📁 文件结构

🔍 环境变量

🛠️ 开发

构建

监听模式

代码检查

📄 许可证

1. 环境配置插件 (`envConfigPlugin`)

2. 版本信息注入插件 (`injectVersionInfoPlugin`)

3. Manifest 生成插件 (`manifestPlugin`)