only-dev

开发环境专用文件替换插件，支持 Vite、Webpack、Rollup 和 Nuxt。允许你在开发时使用 .only-dev 目录中的文件替换原始文件，而无需修改源代码。

功能特性

• ✅ 支持 Vite、Webpack、Rollup 和 Nuxt
• ✅ 热模块替换 (HMR) 支持
• ✅ 文件模式过滤（include/exclude）
• ✅ 自动监听文件变化
• ✅ 开发文件与原始文件映射管理

安装

npm install only-dev
# 或
yarn add only-dev
# 或
pnpm add only-dev

使用方法

Vite

在 vite.config.js 中配置：

import { defineConfig } from 'vite';
import onlyDev from 'only-dev/vite';
// 或
// import onlyDev from 'only-dev';

export default defineConfig({
  plugins: [
    onlyDev({
      enabled: true,        // 是否启用插件，默认 true
      devDir: '.only-dev',  // 开发文件目录，默认 '.only-dev'
      debug: false,         // 是否开启调试日志，默认 false
      exclude: [],          // 排除的文件模式，默认 []
      include: ['**/*']     // 包含的文件模式，默认 ['**/*']
    }),
    // ... 其他插件
  ]
});

若遇到 “ERR_REQUIRE_ESM” 或 “ESM-only 无法被 require” 的报错，请在配置中使用动态 import 加载插件：

import { defineConfig } from 'vite';

export default defineConfig(async () => ({
  plugins: [(await import('only-dev/vite')).default({ devDir: '.only-dev' })]
}));

Webpack

在 webpack.config.js 中配置：

const OnlyDevWebpackPlugin = require('only-dev/webpack');

module.exports = {
  plugins: [
    new OnlyDevWebpackPlugin({
      enabled: true,        // 是否启用插件，默认 true
      devDir: '.only-dev',  // 开发文件目录，默认 '.only-dev'
      debug: false,         // 是否开启调试日志，默认 false
      exclude: [],          // 排除的文件模式，默认 []
      include: ['**/*']     // 包含的文件模式，默认 ['**/*']
    }),
    // ... 其他插件
  ]
};

Rollup

在 rollup.config.js 中配置：

import onlyDev from 'only-dev/rollup';
// 或
// import { rollup as onlyDev } from 'only-dev';

export default {
  plugins: [
    onlyDev({
      enabled: true,        // 是否启用插件，默认 true
      devDir: '.only-dev',  // 开发文件目录，默认 '.only-dev'
      debug: false,         // 是否开启调试日志，默认 false
      exclude: [],          // 排除的文件模式，默认 []
      include: ['**/*']     // 包含的文件模式，默认 ['**/*']
    }),
    // ... 其他插件
  ]
};

Nuxt 3

在 nuxt.config.ts 中配置：

import { defineNuxtConfig } from 'nuxt/config';
import onlyDev from 'only-dev/vite';

export default defineNuxtConfig({
  vite: {
    plugins: [
      onlyDev({
        enabled: true,        // 是否启用插件，默认 true
        devDir: '.only-dev',  // 开发文件目录，默认 '.only-dev'
        debug: false,         // 是否开启调试日志，默认 false
        exclude: [],          // 排除的文件模式，默认 []
        include: ['**/*']     // 包含的文件模式，默认 ['**/*']
      })
    ]
  }
});

注意：Nuxt 3 基于 Vite，因此使用 Vite 版本的插件。插件会在开发环境中自动生效，生产构建时会自动忽略 .only-dev 目录中的文件。

工作原理

1. 插件会在项目根目录下查找 .only-dev 目录
2. 当导入文件时，插件会检查是否存在对应的开发文件
3. 如果存在，则使用开发文件替换原始文件
4. 开发文件的变化会触发热模块替换 (HMR)

目录结构示例

project-root/
├── src/
│   └── components/
│       └── Button.vue
├── .only-dev/          # 开发文件目录
│   └── src/
│       └── components/
│           └── Button.vue  # 这个文件会替换 src/components/Button.vue
└── vite.config.js

配置选项

enabled

• 类型: boolean
• 默认值: true
• 说明: 是否启用插件

devDir

• 类型: string
• 默认值: '.only-dev'
• 说明: 开发文件目录，相对于项目根目录

debug

• 类型: boolean
• 默认值: false
• 说明: 是否开启调试日志，开启后会输出详细的文件替换信息

exclude

• 类型: string[]
• 默认值: []
• 说明: 排除的文件模式（使用 glob patterns），匹配的文件不会被替换

示例：

exclude: ['**/*.test.js', '**/node_modules/**']

include

• 类型: string[]
• 默认值: ['**/*']
• 说明: 包含的文件模式（使用 glob patterns），只有匹配的文件才会被替换

示例：

include: ['src/**/*.vue', 'src/**/*.js']

使用场景

• 开发时临时修改组件或工具函数，而不影响源代码
• 调试特定功能时替换部分文件
• 快速测试不同的实现方案
• 在开发环境中使用 mock 数据

注意事项

1. .only-dev 目录中的文件结构应该与原始文件结构保持一致
2. 开发文件的变化会触发热更新，但可能需要手动刷新浏览器
3. 构建生产版本时，插件会自动忽略 .only-dev 目录中的文件
4. 建议将 .only-dev 目录添加到 .gitignore 中

API (Vite)

插件还提供了一些额外的 API（仅 Vite 版本）：

import onlyDev from 'only-dev/vite';

const plugin = onlyDev({ debug: true });

// 在插件配置后访问 API
plugin.api.getDevFileMap();        // 获取开发文件映射表
plugin.api.getOriginalFiles();     // 获取原始文件内容缓存
plugin.api.restoreOriginalFile(path); // 恢复原始文件

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT

相关链接

• GitHub 仓库
• 问题反馈