only-dev 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# only-dev
+
+[![npm version](https://img.shields.io/npm/v/only-dev.svg)](https://www.npmjs.com/package/only-dev)
+[![npm downloads](https://img.shields.io/npm/dm/only-dev.svg)](https://www.npmjs.com/package/only-dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
+
+开发环境专用文件替换插件，支持 Vite、Webpack 和 Rollup。允许你在开发时使用 `.only-dev` 目录中的文件替换原始文件，而无需修改源代码。
+
+## 功能特性
+
+- ✅ 支持 Vite、Webpack 和 Rollup
+- ✅ 热模块替换 (HMR) 支持
+- ✅ 文件模式过滤（include/exclude）
+- ✅ 自动监听文件变化
+- ✅ 开发文件与原始文件映射管理
+
+## 安装
+
+```bash
+npm install only-dev
+# 或
+yarn add only-dev
+# 或
+pnpm add only-dev
+```
+
+## 使用方法
+
+### Vite
+
+在 `vite.config.js` 中配置：
+
+```javascript
+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: ['**/*']     // 包含的文件模式，默认 ['**/*']
+    }),
+    // ... 其他插件
+  ]
+});
+```
+
+### Webpack
+
+在 `webpack.config.js` 中配置：
+
+```javascript
+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` 中配置：
+
+```javascript
+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: ['**/*']     // 包含的文件模式，默认 ['**/*']
+    }),
+    // ... 其他插件
+  ]
+};
+```
+
+## 工作原理
+
+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），匹配的文件不会被替换
+
+示例：
+```javascript
+exclude: ['**/*.test.js', '**/node_modules/**']
+```
+
+### include
+
+- 类型: `string[]`
+- 默认值: `['**/*']`
+- 说明: 包含的文件模式（使用 glob patterns），只有匹配的文件才会被替换
+
+示例：
+```javascript
+include: ['src/**/*.vue', 'src/**/*.js']
+```
+
+## 使用场景
+
+- 开发时临时修改组件或工具函数，而不影响源代码
+- 调试特定功能时替换部分文件
+- 快速测试不同的实现方案
+- 在开发环境中使用 mock 数据
+
+## 注意事项
+
+1. `.only-dev` 目录中的文件结构应该与原始文件结构保持一致
+2. 开发文件的变化会触发热更新，但可能需要手动刷新浏览器
+3. 构建生产版本时，插件会自动忽略 `.only-dev` 目录中的文件
+4. 建议将 `.only-dev` 目录添加到 `.gitignore` 中
+
+## API (Vite)
+
+插件还提供了一些额外的 API（仅 Vite 版本）：
+
+```javascript
+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 仓库](https://github.com/xujiehui/only-dev)
+- [问题反馈](https://github.com/xujiehui/only-dev/issues)

package/index.js

@@ -0,0 +1,7 @@
+// index.js
+// 主入口文件，默认导出 Vite 插件
+
+export { default } from './vite.js';
+export { default as vite } from './vite.js';
+export { default as rollup } from './rollup.js';
+

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "only-dev",
+  "version": "1.0.0",
+  "description": "开发环境专用文件替换插件，支持 Vite、Webpack 和 Rollup",
+  "type": "module",
+  "main": "index.js",
+  "types": "types.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./vite": "./vite.js",
+    "./webpack": "./webpack.cjs",
+    "./rollup": "./rollup.js"
+  },
+  "keywords": [
+    "vite",
+    "webpack",
+    "rollup",
+    "plugin",
+    "dev",
+    "development",
+    "hot-reload",
+    "hmr"
+  ],
+  "author": "xujiehui",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xujiehui/only-dev.git"
+  },
+  "homepage": "https://github.com/xujiehui/only-dev#readme",
+  "bugs": {
+    "url": "https://github.com/xujiehui/only-dev/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "peerDependencies": {
+    "vite": "^3.0.0 || ^4.0.0 || ^5.0.0",
+    "webpack": "^5.0.0",
+    "rollup": "^3.0.0 || ^4.0.0"
+  },
+  "dependencies": {
+    "minimatch": "^10.0.0"
+  },
+  "devDependencies": {},
+  "files": [
+    "index.js",
+    "vite.js",
+    "webpack.cjs",
+    "rollup.js",
+    "types.d.ts",
+    "README.md"
+  ]
+}
+

package/rollup.js

@@ -0,0 +1,239 @@
+// rollup.js
+import fs from 'fs';
+import path from 'path';
+import minimatch from 'minimatch';
+
+export default function onlyDevRollupPlugin(options = {}) {
+  const {
+    enabled = true,
+    devDir = '.only-dev',
+    debug = false,
+    exclude = [],
+    include = ['**/*']
+  } = options;
+
+  let root = '';
+  const fileMap = new Map();
+  const originalFiles = new Map();
+  const devPathToOriginalPath = new Map();
+
+  return {
+    name: 'only-dev',
+
+    buildStart(opts) {
+      root = opts.input ? path.dirname(Array.isArray(opts.input) ? opts.input[0] : opts.input) : process.cwd();
+      
+      if (debug) {
+        console.log(`[only-dev] Rollup 插件已加载，根目录: ${root}`);
+      }
+    },
+
+    resolveId(source, importer) {
+      if (!enabled) return null;
+
+      try {
+        // 解析导入路径
+        let resolvedPath;
+        
+        if (path.isAbsolute(source)) {
+          resolvedPath = source;
+        } else if (importer) {
+          resolvedPath = path.resolve(path.dirname(importer), source);
+        } else {
+          resolvedPath = path.resolve(root, source);
+        }
+
+        // 规范化路径
+        resolvedPath = path.resolve(resolvedPath);
+        
+        // 检查是否有对应的开发文件
+        const devPath = getDevPath(resolvedPath);
+        if (devPath && fs.existsSync(devPath)) {
+          const normalizedResolved = normalizePath(resolvedPath);
+          const normalizedDevPath = normalizePath(devPath);
+          
+          if (debug) {
+            console.log(`[only-dev] 解析: ${path.relative(root, resolvedPath)} -> ${path.relative(root, devPath)}`);
+          }
+          
+          fileMap.set(normalizedResolved, normalizedDevPath);
+          devPathToOriginalPath.set(normalizedDevPath, normalizedResolved);
+          
+          return devPath;
+        }
+
+        return null;
+      } catch (err) {
+        if (debug) {
+          console.error('[only-dev] 解析错误:', err);
+        }
+        return null;
+      }
+    },
+
+    load(id) {
+      if (!enabled) return null;
+
+      const normalizedId = normalizePath(id);
+
+      // 如果已经在 .only-dev 目录中，直接读取
+      if (normalizedId.includes(`/${devDir}/`)) {
+        try {
+          if (!fs.existsSync(id)) {
+            if (debug) {
+              console.warn(`[only-dev] load: 开发文件不存在: ${path.relative(root || process.cwd(), id)}`);
+            }
+            return null;
+          }
+          
+          const originalPath = getOriginalPath(normalizedId);
+          const normalizedOriginalPath = normalizePath(originalPath);
+          
+          // 读取最新的文件内容
+          const content = fs.readFileSync(id, 'utf-8');
+          
+          // 缓存原始文件内容（仅在首次加载时）
+          if (!originalFiles.has(normalizedOriginalPath) && fs.existsSync(originalPath)) {
+            originalFiles.set(normalizedOriginalPath, fs.readFileSync(originalPath, 'utf-8'));
+          }
+          
+          // 更新映射关系
+          fileMap.set(normalizedOriginalPath, normalizedId);
+          devPathToOriginalPath.set(normalizedId, normalizedOriginalPath);
+          
+          if (debug) {
+            console.log(`[only-dev] load: 加载开发文件: ${path.relative(root || process.cwd(), id)}`);
+          }
+          
+          return content;
+        } catch (err) {
+          if (debug) {
+            console.error('[only-dev] load: 读取文件错误:', err);
+          }
+          return null;
+        }
+      }
+      
+      // 检查是否有对应的 .only-dev 文件
+      const devPath = getDevPath(id);
+      if (devPath && fs.existsSync(devPath)) {
+        try {
+          const normalizedDevPath = normalizePath(devPath);
+          const normalizedOriginalId = normalizePath(id);
+          
+          // 读取最新的文件内容
+          const content = fs.readFileSync(devPath, 'utf-8');
+          
+          // 更新映射关系
+          fileMap.set(normalizedOriginalId, normalizedDevPath);
+          devPathToOriginalPath.set(normalizedDevPath, normalizedOriginalId);
+          
+          // 缓存原始文件内容（仅在首次加载时）
+          if (!originalFiles.has(normalizedOriginalId) && fs.existsSync(id)) {
+            originalFiles.set(normalizedOriginalId, fs.readFileSync(id, 'utf-8'));
+          }
+          
+          if (debug) {
+            console.log(`[only-dev] load: 使用开发文件 (原始: ${path.relative(root || process.cwd(), id)}, 开发: ${path.relative(root || process.cwd(), devPath)})`);
+          }
+          
+          return content;
+        } catch (err) {
+          if (debug) {
+            console.error('[only-dev] load: 读取开发文件错误:', err);
+          }
+          return null;
+        }
+      }
+
+      return null;
+    },
+
+    watchChange(id) {
+      if (!enabled) return;
+
+      const normalizedFile = normalizePath(id);
+      const devDirNormalized = normalizePath(path.join(root || process.cwd(), devDir));
+      
+      // 检查是否是 .only-dev 目录下的文件
+      if (normalizedFile.startsWith(devDirNormalized + '/') || normalizedFile.includes(`/${devDir}/`)) {
+        const originalPath = getOriginalPath(normalizedFile);
+        const normalizedOriginalPath = normalizePath(originalPath);
+        
+        if (debug) {
+          console.log(`[only-dev] 开发文件变更: ${path.relative(root || process.cwd(), id)}`);
+          console.log(`[only-dev] 原始路径: ${path.relative(root || process.cwd(), originalPath)}`);
+        }
+        
+        // 更新映射关系
+        devPathToOriginalPath.set(normalizedFile, normalizedOriginalPath);
+        fileMap.set(normalizedOriginalPath, normalizedFile);
+      }
+    },
+
+    buildEnd() {
+      if (debug && enabled) {
+        console.log(`[only-dev] 构建完成，共使用 ${fileMap.size} 个开发文件`);
+      }
+    }
+  };
+
+  function getDevPath(originalPath) {
+    const currentRoot = root || process.cwd();
+    if (!originalPath.startsWith(currentRoot)) return null;
+    
+    const relativePath = path.relative(currentRoot, originalPath);
+    const devPath = path.join(currentRoot, devDir, relativePath);
+    
+    // 检查是否在排除列表中
+    if (exclude.some(pattern => minimatch(relativePath, pattern))) {
+      return null;
+    }
+    
+    // 检查是否在包含列表中
+    if (include.length > 0 && !include.some(pattern => minimatch(relativePath, pattern))) {
+      return null;
+    }
+    
+    return devPath;
+  }
+
+  function getOriginalPath(devPath) {
+    const normalizedDevPath = normalizePath(devPath);
+    const currentRoot = root || process.cwd();
+    const devDirNormalized = normalizePath(path.join(currentRoot, devDir));
+    
+    // 如果不在 .only-dev 目录中，直接返回
+    if (!normalizedDevPath.startsWith(devDirNormalized + '/') && !normalizedDevPath.includes(`/${devDir}/`)) {
+      return devPath;
+    }
+    
+    // 从映射中查找（优先使用缓存）
+    if (devPathToOriginalPath.has(normalizedDevPath)) {
+      return devPathToOriginalPath.get(normalizedDevPath);
+    }
+    
+    // 通过路径计算原始路径
+    let relativeFromDev;
+    const devDirIndex = normalizedDevPath.indexOf(`/${devDir}/`);
+    if (devDirIndex !== -1) {
+      relativeFromDev = normalizedDevPath.substring(devDirIndex + devDir.length + 2);
+    } else if (normalizedDevPath.startsWith(devDirNormalized + '/')) {
+      relativeFromDev = normalizedDevPath.substring(devDirNormalized.length + 1);
+    } else {
+      return devPath;
+    }
+    
+    const originalPath = normalizePath(path.join(currentRoot, relativeFromDev));
+    
+    // 更新映射关系
+    devPathToOriginalPath.set(normalizedDevPath, originalPath);
+    
+    return originalPath;
+  }
+
+  function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+  }
+}
+

package/types.d.ts

@@ -0,0 +1,84 @@
+// types.d.ts
+import { Plugin } from 'vite';
+
+export interface OnlyDevOptions {
+  /**
+   * 是否启用插件
+   * @default true
+   */
+  enabled?: boolean;
+  
+  /**
+   * 开发文件目录
+   * @default '.only-dev'
+   */
+  devDir?: string;
+  
+  /**
+   * 是否开启调试日志
+   * @default false
+   */
+  debug?: boolean;
+  
+  /**
+   * 排除的文件模式（glob patterns）
+   * @default []
+   */
+  exclude?: string[];
+  
+  /**
+   * 包含的文件模式（glob patterns）
+   * @default ['**/*']
+   */
+  include?: string[];
+}
+
+export interface OnlyDevApi {
+  /**
+   * 获取开发文件映射表
+   */
+  getDevFileMap: () => Map<string, string>;
+  
+  /**
+   * 获取原始文件内容缓存
+   */
+  getOriginalFiles: () => Map<string, string>;
+  
+  /**
+   * 恢复原始文件
+   * @param filePath 文件路径
+   * @returns 是否成功恢复
+   */
+  restoreOriginalFile: (filePath: string) => boolean;
+}
+
+/**
+ * Vite 插件
+ */
+export declare function onlyDevVitePlugin(options?: OnlyDevOptions): Plugin & {
+  api: OnlyDevApi;
+};
+
+/**
+ * Webpack 插件类
+ */
+export declare class OnlyDevWebpackPlugin {
+  constructor(options?: OnlyDevOptions);
+  apply(compiler: any): void;
+}
+
+/**
+ * Rollup 插件
+ */
+export declare function onlyDevRollupPlugin(options?: OnlyDevOptions): {
+  name: string;
+  buildStart: (opts: any) => void;
+  resolveId: (source: string, importer?: string) => string | null;
+  load: (id: string) => string | null;
+  watchChange: (id: string) => void;
+  buildEnd: () => void;
+};
+
+declare const _default: typeof onlyDevVitePlugin;
+export default _default;
+

package/vite.js

@@ -0,0 +1,381 @@
+// vite.js
+import fs from 'fs';
+import path from 'path';
+import { normalizePath } from 'vite';
+import minimatch from 'minimatch';
+
+export default function onlyDevPlugin(options = {}) {
+  const {
+    enabled = true,
+    devDir = '.only-dev',
+    debug = false,
+    exclude = [],
+    include = ['**/*']
+  } = options;
+
+  let root = '';
+  let config;
+  const fileMap = new Map();
+  const originalFiles = new Map();
+  const devPathToOriginalPath = new Map();
+
+  return {
+    name: 'only-dev',
+    enforce: 'pre',
+
+    configResolved(resolvedConfig) {
+      root = resolvedConfig.root;
+      config = resolvedConfig;
+      
+      if (debug) {
+        console.log(`[only-dev] 插件已加载，根目录: ${root}`);
+      }
+    },
+
+    configureServer(server) {
+      if (!enabled) return;
+
+      // 监听 .only-dev 目录变化
+      const devDirPath = path.join(root, devDir);
+      
+      // 检查目录是否存在
+      if (!fs.existsSync(devDirPath)) {
+        if (debug) {
+          console.log(`[only-dev] 开发目录不存在: ${devDirPath}`);
+        }
+        return;
+      }
+
+      // 使用 Vite 的 watcher 来监听文件变化
+      const watcher = server.watcher;
+      
+      // 添加 .only-dev 目录到监听列表
+      watcher.add(devDirPath);
+
+      // 注意：我们不在 watcher.on('change') 中处理，而是使用 handleHotUpdate hook
+      // 这样可以确保 Vite 正确处理文件变化
+    },
+
+    handleHotUpdate(ctx) {
+      if (!enabled) return;
+
+      const { file, server } = ctx;
+      const normalizedFile = normalizePath(file);
+      
+      // 检查是否是 .only-dev 目录下的文件（使用更精确的路径匹配）
+      const devDirNormalized = normalizePath(path.join(root, devDir));
+      if (!normalizedFile.startsWith(devDirNormalized + '/') && !normalizedFile.includes(`/${devDir}/`)) {
+        return;
+      }
+
+      const originalPath = getOriginalPath(normalizedFile);
+      const normalizedOriginalPath = normalizePath(originalPath);
+      
+      if (debug) {
+        console.log(`[only-dev] handleHotUpdate: 开发文件变更: ${path.relative(root, file)}`);
+        console.log(`[only-dev] handleHotUpdate: 原始路径: ${path.relative(root, originalPath)}`);
+      }
+
+      // 更新 devPathToOriginalPath 映射
+      devPathToOriginalPath.set(normalizedFile, normalizedOriginalPath);
+      
+      // 更新 fileMap 映射
+      fileMap.set(normalizedOriginalPath, normalizedFile);
+
+      // 查找对应的模块 - 优先通过 dev 路径查找（因为 resolveId 已经将 ID 改成了 dev 路径）
+      let module = server.moduleGraph.getModuleById(normalizedFile);
+      
+      // 如果找不到，尝试通过原始路径查找
+      if (!module) {
+        module = server.moduleGraph.getModuleById(normalizedOriginalPath);
+      }
+
+      // 如果还是找不到，尝试通过 fileMap 查找所有可能的模块
+      if (!module) {
+        for (const [id, devPath] of fileMap.entries()) {
+          const normalizedDevPath = normalizePath(devPath);
+          if (normalizedDevPath === normalizedFile || normalizePath(id) === normalizedOriginalPath) {
+            // 尝试通过原始 ID 查找
+            module = server.moduleGraph.getModuleById(id);
+            if (module) break;
+            // 尝试通过 dev 路径查找
+            module = server.moduleGraph.getModuleById(normalizedDevPath);
+            if (module) break;
+          }
+        }
+      }
+
+      // 如果还是找不到，尝试通过 URL 查找
+      if (!module) {
+        const relativePath = path.relative(root, originalPath).replace(/\\/g, '/');
+        const url = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+        module = server.moduleGraph.urlToModuleMap.get(url);
+      }
+
+      // 如果还是找不到，尝试遍历所有模块查找匹配的
+      if (!module) {
+        for (const mod of server.moduleGraph.idToModuleMap.values()) {
+          const modId = normalizePath(mod.id);
+          if (modId === normalizedOriginalPath || 
+              modId === normalizedFile ||
+              modId.includes(`/${devDir}/`) && getOriginalPath(modId) === normalizedOriginalPath) {
+            module = mod;
+            break;
+          }
+        }
+      }
+
+      if (module) {
+        if (debug) {
+          console.log(`[only-dev] handleHotUpdate: 找到模块: ${module.id}`);
+          console.log(`[only-dev] handleHotUpdate: 模块 URL: ${module.url}`);
+        }
+        
+        // 确保映射关系是最新的
+        const devPath = getDevPath(normalizedOriginalPath);
+        if (devPath && fs.existsSync(devPath)) {
+          const normalizedDevPath = normalizePath(devPath);
+          
+          // 更新映射关系
+          fileMap.set(normalizedOriginalPath, normalizedDevPath);
+          devPathToOriginalPath.set(normalizedDevPath, normalizedOriginalPath);
+          
+          if (debug) {
+            console.log(`[only-dev] handleHotUpdate: 更新映射: ${normalizedOriginalPath} -> ${normalizedDevPath}`);
+          }
+        }
+        
+        // 使模块失效，触发重新加载
+        // 传入空的 Set 表示不递归失效依赖，让 Vite 的 HMR 机制自动处理
+        server.moduleGraph.invalidateModule(module, new Set());
+        
+        // 清除模块的转换缓存，确保重新加载时使用最新内容
+        if (module.transformResult) {
+          module.transformResult = null;
+        }
+        
+        if (debug) {
+          console.log(`[only-dev] handleHotUpdate: 已使模块失效: ${module.id}`);
+        }
+        
+        // 返回模块列表，让 Vite 处理 HMR
+        // Vite 会自动向上查找 HMR 边界（如 Vue 组件），只更新必要的部分
+        return [module];
+      } else {
+        if (debug) {
+          console.log(`[only-dev] handleHotUpdate: 未找到模块`);
+          console.log(`[only-dev] handleHotUpdate: 尝试查找的路径: ${normalizedOriginalPath}, ${normalizedFile}`);
+          console.log(`[only-dev] handleHotUpdate: 模块图大小: ${server.moduleGraph.idToModuleMap.size}`);
+        }
+        // 返回 undefined 会触发全量刷新
+        return undefined;
+      }
+    },
+
+    async resolveId(source, importer, options) {
+      if (!enabled) return null;
+
+      try {
+        const resolved = await this.resolve(source, importer, {
+          skipSelf: true,
+          ...options
+        });
+
+        if (!resolved) return null;
+
+        const devPath = getDevPath(resolved.id);
+        if (devPath && fs.existsSync(devPath)) {
+          const normalizedResolved = normalizePath(resolved.id);
+          const normalizedDevPath = normalizePath(devPath);
+          
+          if (debug) {
+            console.log(`[only-dev] 解析: ${path.relative(root, resolved.id)} -> ${path.relative(root, devPath)}`);
+          }
+          
+          fileMap.set(normalizedResolved, normalizedDevPath);
+          devPathToOriginalPath.set(normalizedDevPath, normalizedResolved);
+          
+          return normalizedDevPath;
+        }
+
+        return null;
+      } catch (err) {
+        if (debug) {
+          console.error('[only-dev] 解析错误:', err);
+        }
+        return null;
+      }
+    },
+
+    async load(id) {
+      if (!enabled) return null;
+
+      const normalizedId = normalizePath(id);
+
+      // 如果已经在 .only-dev 目录中，直接读取（热更新时会走这里）
+      if (normalizedId.includes(`/${devDir}/`)) {
+        try {
+          // 检查文件是否存在
+          if (!fs.existsSync(id)) {
+            if (debug) {
+              console.warn(`[only-dev] load: 开发文件不存在: ${path.relative(root, id)}`);
+            }
+            return null;
+          }
+          
+          const originalPath = getOriginalPath(normalizedId);
+          const normalizedOriginalPath = normalizePath(originalPath);
+          
+          // 读取最新的文件内容（不缓存，确保热更新时获取最新内容）
+          const content = fs.readFileSync(id, 'utf-8');
+          
+          // 缓存原始文件内容（仅在首次加载时）
+          if (!originalFiles.has(normalizedOriginalPath) && fs.existsSync(originalPath)) {
+            originalFiles.set(normalizedOriginalPath, fs.readFileSync(originalPath, 'utf-8'));
+          }
+          
+          // 更新映射关系
+          fileMap.set(normalizedOriginalPath, normalizedId);
+          devPathToOriginalPath.set(normalizedId, normalizedOriginalPath);
+          
+          if (debug) {
+            console.log(`[only-dev] load: 加载开发文件: ${path.relative(root, id)}`);
+          }
+          
+          return content;
+        } catch (err) {
+          if (debug) {
+            console.error('[only-dev] load: 读取文件错误:', err);
+          }
+          return null;
+        }
+      }
+      
+      // 检查是否有对应的 .only-dev 文件
+      const devPath = getDevPath(id);
+      if (devPath && fs.existsSync(devPath)) {
+        try {
+          const normalizedDevPath = normalizePath(devPath);
+          const normalizedOriginalId = normalizePath(id);
+          
+          // 读取最新的文件内容
+          const content = fs.readFileSync(devPath, 'utf-8');
+          
+          // 更新映射关系
+          fileMap.set(normalizedOriginalId, normalizedDevPath);
+          devPathToOriginalPath.set(normalizedDevPath, normalizedOriginalId);
+          
+          // 缓存原始文件内容（仅在首次加载时）
+          if (!originalFiles.has(normalizedOriginalId) && fs.existsSync(id)) {
+            originalFiles.set(normalizedOriginalId, fs.readFileSync(id, 'utf-8'));
+          }
+          
+          if (debug) {
+            console.log(`[only-dev] load: 使用开发文件 (原始: ${path.relative(root, id)}, 开发: ${path.relative(root, devPath)})`);
+          }
+          
+          return content;
+        } catch (err) {
+          if (debug) {
+            console.error('[only-dev] load: 读取开发文件错误:', err);
+          }
+          return null;
+        }
+      }
+
+      return null;
+    },
+
+    async transform(code, id) {
+      if (!enabled) return null;
+
+      const normalizedId = normalizePath(id);
+
+      // 检查是否来自 .only-dev 目录
+      if (fileMap.has(normalizedId) || devPathToOriginalPath.has(normalizedId) || normalizedId.includes(`/${devDir}/`)) {
+        if (debug) {
+          const from = normalizedId.includes(`/${devDir}/`) 
+            ? '直接' : '映射';
+          console.log(`[only-dev] ${from}使用开发文件转换: ${path.relative(root, id)}`);
+        }
+      }
+
+      return null;
+    },
+
+    generateBundle() {
+      if (debug && enabled) {
+        console.log(`[only-dev] 构建完成，共使用 ${fileMap.size} 个开发文件`);
+      }
+    },
+
+    // 提供额外的工具函数
+    api: {
+      getDevFileMap: () => new Map(fileMap),
+      getOriginalFiles: () => new Map(originalFiles),
+      restoreOriginalFile: (filePath) => {
+        const content = originalFiles.get(filePath);
+        if (content) {
+          fs.writeFileSync(filePath, content);
+          return true;
+        }
+        return false;
+      }
+    }
+  };
+
+  function getDevPath(originalPath) {
+    if (!originalPath.startsWith(root)) return null;
+    
+    const relativePath = path.relative(root, originalPath);
+    const devPath = path.join(root, devDir, relativePath);
+    
+    // 检查是否在排除列表中
+    if (exclude.some(pattern => minimatch(relativePath, pattern))) {
+      return null;
+    }
+    
+    // 检查是否在包含列表中
+    // 如果 include 为空数组，表示不限制（包含所有文件）
+    // 如果 include 不为空，文件必须匹配至少一个模式
+    if (include.length > 0 && !include.some(pattern => minimatch(relativePath, pattern))) {
+      return null;
+    }
+    
+    return devPath;
+  }
+
+  function getOriginalPath(devPath) {
+    const normalizedDevPath = normalizePath(devPath);
+    const devDirNormalized = normalizePath(path.join(root, devDir));
+    
+    // 如果不在 .only-dev 目录中，直接返回
+    if (!normalizedDevPath.startsWith(devDirNormalized + '/') && !normalizedDevPath.includes(`/${devDir}/`)) {
+      return devPath;
+    }
+    
+    // 从映射中查找（优先使用缓存）
+    if (devPathToOriginalPath.has(normalizedDevPath)) {
+      return devPathToOriginalPath.get(normalizedDevPath);
+    }
+    
+    // 通过路径计算原始路径
+    let relativeFromDev;
+    const devDirIndex = normalizedDevPath.indexOf(`/${devDir}/`);
+    if (devDirIndex !== -1) {
+      relativeFromDev = normalizedDevPath.substring(devDirIndex + devDir.length + 2);
+    } else if (normalizedDevPath.startsWith(devDirNormalized + '/')) {
+      relativeFromDev = normalizedDevPath.substring(devDirNormalized.length + 1);
+    } else {
+      return devPath;
+    }
+    
+    const originalPath = normalizePath(path.join(root, relativeFromDev));
+    
+    // 更新映射关系
+    devPathToOriginalPath.set(normalizedDevPath, originalPath);
+    
+    return originalPath;
+  }
+}
+

package/webpack.cjs

@@ -0,0 +1,270 @@
+// webpack.js
+const fs = require('fs');
+const path = require('path');
+const minimatch = require('minimatch');
+
+class OnlyDevWebpackPlugin {
+  constructor(options = {}) {
+    this.options = {
+      enabled: options.enabled !== false,
+      devDir: options.devDir || '.only-dev',
+      debug: options.debug || false,
+      exclude: options.exclude || [],
+      include: options.include || ['**/*']
+    };
+    
+    this.root = '';
+    this.fileMap = new Map();
+    this.originalFiles = new Map();
+    this.devPathToOriginalPath = new Map();
+  }
+
+  apply(compiler) {
+    if (!this.options.enabled) return;
+
+    const { devDir, debug } = this.options;
+    
+    // 获取项目根目录
+    this.root = compiler.context || compiler.options.context || process.cwd();
+    
+    if (debug) {
+      console.log(`[only-dev] Webpack 插件已加载，根目录: ${this.root}`);
+    }
+
+    // 监听文件变化
+    compiler.hooks.normalModuleFactory.tap('OnlyDevWebpackPlugin', (normalModuleFactory) => {
+      // 在解析模块时替换路径
+      normalModuleFactory.hooks.beforeResolve.tapAsync('OnlyDevWebpackPlugin', (data, callback) => {
+        if (!data.request) {
+          return callback();
+        }
+
+        // 解析请求路径
+        const request = data.request;
+        const context = data.context || this.root;
+        
+        // 尝试解析为绝对路径
+        let resolvedPath;
+        try {
+          resolvedPath = require.resolve(request, { paths: [context] });
+        } catch (err) {
+          // 如果解析失败，尝试使用路径拼接
+          if (path.isAbsolute(request)) {
+            resolvedPath = request;
+          } else {
+            resolvedPath = path.resolve(context, request);
+          }
+        }
+
+        // 检查是否有对应的开发文件
+        const devPath = this.getDevPath(resolvedPath);
+        if (devPath && fs.existsSync(devPath)) {
+          const normalizedResolved = this.normalizePath(resolvedPath);
+          const normalizedDevPath = this.normalizePath(devPath);
+          
+          if (debug) {
+            console.log(`[only-dev] 解析: ${path.relative(this.root, resolvedPath)} -> ${path.relative(this.root, devPath)}`);
+          }
+          
+          this.fileMap.set(normalizedResolved, normalizedDevPath);
+          this.devPathToOriginalPath.set(normalizedDevPath, normalizedResolved);
+          
+          // 修改请求路径
+          data.request = devPath;
+        }
+
+        callback();
+      });
+
+      // 在创建模块时读取开发文件内容
+      normalModuleFactory.hooks.module.tap('OnlyDevWebpackPlugin', (module, data) => {
+        const resource = module.resource;
+        if (!resource) return module;
+
+        const normalizedResource = this.normalizePath(resource);
+        
+        // 如果已经在 .only-dev 目录中，确保内容是最新的
+        if (normalizedResource.includes(`/${devDir}/`)) {
+          const originalPath = this.getOriginalPath(normalizedResource);
+          const normalizedOriginalPath = this.normalizePath(originalPath);
+          
+          // 缓存原始文件内容（仅在首次加载时）
+          if (!this.originalFiles.has(normalizedOriginalPath) && fs.existsSync(originalPath)) {
+            this.originalFiles.set(normalizedOriginalPath, fs.readFileSync(originalPath, 'utf-8'));
+          }
+          
+          // 更新映射关系
+          this.fileMap.set(normalizedOriginalPath, normalizedResource);
+          this.devPathToOriginalPath.set(normalizedResource, normalizedOriginalPath);
+          
+          if (debug) {
+            console.log(`[only-dev] 加载开发文件: ${path.relative(this.root, resource)}`);
+          }
+        } else {
+          // 检查是否有对应的开发文件
+          const devPath = this.getDevPath(resource);
+          if (devPath && fs.existsSync(devPath)) {
+            const normalizedDevPath = this.normalizePath(devPath);
+            const normalizedResource = this.normalizePath(resource);
+            
+            // 更新映射关系
+            this.fileMap.set(normalizedResource, normalizedDevPath);
+            this.devPathToOriginalPath.set(normalizedDevPath, normalizedResource);
+            
+            // 缓存原始文件内容（仅在首次加载时）
+            if (!this.originalFiles.has(normalizedResource) && fs.existsSync(resource)) {
+              this.originalFiles.set(normalizedResource, fs.readFileSync(resource, 'utf-8'));
+            }
+            
+            if (debug) {
+              console.log(`[only-dev] 使用开发文件 (原始: ${path.relative(this.root, resource)}, 开发: ${path.relative(this.root, devPath)})`);
+            }
+          }
+        }
+
+        return module;
+      });
+    });
+
+    // 监听文件变化，触发热更新
+    compiler.hooks.afterCompile.tap('OnlyDevWebpackPlugin', (compilation) => {
+      const devDirPath = path.join(this.root, devDir);
+      
+      if (!fs.existsSync(devDirPath)) {
+        if (debug) {
+          console.log(`[only-dev] 开发目录不存在: ${devDirPath}`);
+        }
+        return;
+      }
+
+      // 添加开发目录到文件依赖中，以便监听变化
+      compilation.fileDependencies.add(devDirPath);
+      
+      // 递归添加所有开发文件
+      this.addDirectoryToDependencies(devDirPath, compilation);
+    });
+
+    // 监听文件变化
+    compiler.hooks.watchRun.tapAsync('OnlyDevWebpackPlugin', (compilation, callback) => {
+      const changedFiles = compilation.modifiedFiles || new Set();
+      
+      for (const file of changedFiles) {
+        const normalizedFile = this.normalizePath(file);
+        const devDirNormalized = this.normalizePath(path.join(this.root, devDir));
+        
+        // 检查是否是 .only-dev 目录下的文件
+        if (normalizedFile.startsWith(devDirNormalized + '/') || normalizedFile.includes(`/${devDir}/`)) {
+          const originalPath = this.getOriginalPath(normalizedFile);
+          const normalizedOriginalPath = this.normalizePath(originalPath);
+          
+          if (debug) {
+            console.log(`[only-dev] 开发文件变更: ${path.relative(this.root, file)}`);
+            console.log(`[only-dev] 原始路径: ${path.relative(this.root, originalPath)}`);
+          }
+          
+          // 更新映射关系
+          this.devPathToOriginalPath.set(normalizedFile, normalizedOriginalPath);
+          this.fileMap.set(normalizedOriginalPath, normalizedFile);
+          
+          // 使相关模块失效，触发重新编译
+          if (compilation.moduleGraph) {
+            const module = compilation.moduleGraph.getModuleByDependency(
+              compilation.moduleGraph.getResolvedModule(normalizedOriginalPath)
+            );
+            if (module) {
+              compilation.moduleGraph.invalidateModule(module);
+            }
+          }
+        }
+      }
+      
+      callback();
+    });
+
+    // 构建完成时的日志
+    compiler.hooks.done.tap('OnlyDevWebpackPlugin', () => {
+      if (debug && this.options.enabled) {
+        console.log(`[only-dev] 构建完成，共使用 ${this.fileMap.size} 个开发文件`);
+      }
+    });
+  }
+
+  addDirectoryToDependencies(dirPath, compilation) {
+    try {
+      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        
+        if (entry.isDirectory()) {
+          this.addDirectoryToDependencies(fullPath, compilation);
+        } else {
+          compilation.fileDependencies.add(fullPath);
+        }
+      }
+    } catch (err) {
+      if (this.options.debug) {
+        console.error(`[only-dev] 添加依赖错误:`, err);
+      }
+    }
+  }
+
+  getDevPath(originalPath) {
+    if (!originalPath.startsWith(this.root)) return null;
+    
+    const relativePath = path.relative(this.root, originalPath);
+    const devPath = path.join(this.root, this.options.devDir, relativePath);
+    
+    // 检查是否在排除列表中
+    if (this.options.exclude.some(pattern => minimatch(relativePath, pattern))) {
+      return null;
+    }
+    
+    // 检查是否在包含列表中
+    if (this.options.include.length > 0 && !this.options.include.some(pattern => minimatch(relativePath, pattern))) {
+      return null;
+    }
+    
+    return devPath;
+  }
+
+  getOriginalPath(devPath) {
+    const normalizedDevPath = this.normalizePath(devPath);
+    const devDirNormalized = this.normalizePath(path.join(this.root, this.options.devDir));
+    
+    // 如果不在 .only-dev 目录中，直接返回
+    if (!normalizedDevPath.startsWith(devDirNormalized + '/') && !normalizedDevPath.includes(`/${this.options.devDir}/`)) {
+      return devPath;
+    }
+    
+    // 从映射中查找（优先使用缓存）
+    if (this.devPathToOriginalPath.has(normalizedDevPath)) {
+      return this.devPathToOriginalPath.get(normalizedDevPath);
+    }
+    
+    // 通过路径计算原始路径
+    let relativeFromDev;
+    const devDirIndex = normalizedDevPath.indexOf(`/${this.options.devDir}/`);
+    if (devDirIndex !== -1) {
+      relativeFromDev = normalizedDevPath.substring(devDirIndex + this.options.devDir.length + 2);
+    } else if (normalizedDevPath.startsWith(devDirNormalized + '/')) {
+      relativeFromDev = normalizedDevPath.substring(devDirNormalized.length + 1);
+    } else {
+      return devPath;
+    }
+    
+    const originalPath = this.normalizePath(path.join(this.root, relativeFromDev));
+    
+    // 更新映射关系
+    this.devPathToOriginalPath.set(normalizedDevPath, originalPath);
+    
+    return originalPath;
+  }
+
+  normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+  }
+}
+
+module.exports = OnlyDevWebpackPlugin;
+