@gylautorun/dev-proxy-cookie 1.0.0 → 1.0.2

package/src/proxy/vue-proxy-config.ts

@@ -1,41 +1,98 @@
+/**
+ * Vue CLI 代理配置模块
+ * 
+ * 提供 Vue CLI 开发服务器的代理配置功能，支持从文件读取 Cookie 并注入代理请求。
+ * 核心函数包括 createFileCookieGetter 和 createVueProxyConfig。
+ * 
+ * @module vue-proxy-config
+ */
 import type { IncomingMessage } from 'http';
 import * as path from 'path';
-import { CookieReader, watchCookieFile } from '../utils';
+import { CookieReader, watchCookieFile, shouldEnableWatch } from '../utils';
 import { applyDevCookieHeader } from './apply-dev-cookie-header';
 
 /** Options for {@link createFileCookieGetter}. */
 export interface CreateFileCookieGetterOptions {
   /**
-   * Watch the file for logging when it changes. Cookie value is always read from disk on each proxy request,
-   * so you do not need a dev-server restart when this is false.
-   * @default true
+   * 是否监听文件变化
+   * - true: 始终监听
+   * - false: 从不监听
+   * - 'auto': 根据环境自动判断（默认）
+   * 
+   * Cookie 值每次代理请求时都会从磁盘读取，因此即使 watch 为 false，
+   * 修改 cookie 文件后也不需要重启开发服务器。
+   * @default 'auto'
    */
-  watch?: boolean;
+  watch?: boolean | 'auto';
   /** Log when the cookie file changes (only if `watch` is true). @default false */
   debug?: boolean;
+  /** 
+   * 自定义生产环境变量名称列表，用于判断是否禁用监听
+   * 例如: ['MY_APP_ENV', 'BUILD_TYPE']
+   */
+  productionEnvs?: string[];
+  /**
+   * 是否为开发环境（优先级最高）
+   * 设置此参数后，将直接决定是否启用文件监听：
+   * - true: 启用监听（开发模式）
+   * - false: 禁用监听（生产模式）
+   * 
+   * 使用示例: isDev: process.env.NODE_ENV === 'development'
+   */
+  isDev?: boolean;
 }
 
+/**
+ * Vue 代理配置选项
+ */
 export interface VueProxyConfigOptions {
+  /** Cookie 获取函数 */
   getCookie?: () => string;
+  /** 是否输出调试日志 */
   debug?: boolean;
+  /** 自定义请求头 */
   headers?: Record<string, string>;
+  /** 是否启用 WebSocket 代理 */
   ws?: boolean;
+  /** 是否修改请求头中的 Origin */
   changeOrigin?: boolean;
+  /** 是否验证 SSL 证书 */
   secure?: boolean;
+  /** 错误回调函数 */
   onError?: (err: Error) => void;
 }
 
+/**
+ * Vue CLI 代理配置接口
+ * 
+ * 符合 Vue CLI 代理配置格式的对象结构
+ */
 export interface ProxyConfig {
+  /** 是否启用 WebSocket 代理 */
   ws: boolean;
+  /** 代理目标地址 */
   target: string;
+  /** 是否修改请求头中的 Origin */
   changeOrigin: boolean;
+  /** 是否验证 SSL 证书 */
   secure: boolean;
+  /** 代理请求前的回调函数 */
   onProxyReq: (proxyReq: any, req: IncomingMessage) => void;
+  /** 代理响应后的回调函数（可选） */
   onProxyRes?: (proxyRes: any, req: IncomingMessage) => void;
+  /** 错误处理回调函数 */
   onError: (err: Error) => void;
+  /** 自定义请求头 */
   headers?: Record<string, string>;
 }
 
+/**
+ * 创建 Vue CLI 代理配置
+ * 
+ * @param target - 代理目标地址
+ * @param options - 配置选项
+ * @returns Vue CLI 代理配置对象
+ */
 export function createVueProxyConfig(
   target: string,
   options: VueProxyConfigOptions = {}
@@ -74,14 +131,43 @@ export function createVueProxyConfig(
   return config;
 }
 
+/**
+ * 创建文件 Cookie 获取器
+ * 
+ * 从指定文件读取 Cookie 值，支持文件监听功能。
+ * 
+ * @param cookieFile - Cookie 文件路径
+ * @param options - 配置选项
+ * @returns Cookie 获取函数
+ */
 export function createFileCookieGetter(
   cookieFile: string,
   options: CreateFileCookieGetterOptions = {}
 ): () => string {
-  const { watch = true, debug = false } = options;
-  const reader = new CookieReader({ cookieFile: path.resolve(cookieFile) });
-
-  if (watch) {
+  const { 
+    watch = 'auto', 
+    debug = true,
+    productionEnvs = [],
+    isDev 
+  } = options;
+  const reader = new CookieReader({ cookieFile: path.resolve(cookieFile) }, debug);
+
+  // 判断是否应该启用监听
+  // isDev 参数优先级最高，直接决定是否启用监听
+  let shouldWatch: boolean;
+  
+  if (isDev !== undefined) {
+    // 用户显式设置了 isDev 参数
+    shouldWatch = isDev;
+    if (debug) {
+      console.log(`[CookieFile] isDev=${isDev}, ${shouldWatch ? 'enabling' : 'disabling'} watch`);
+    }
+  } else {
+    // 使用智能环境检测
+    shouldWatch = shouldEnableWatch(watch, productionEnvs, debug, '[CookieFile]');
+  }
+  
+  if (shouldWatch) {
     watchCookieFile(
       path.resolve(cookieFile),
       (newCookie) => {
@@ -93,18 +179,35 @@ export function createFileCookieGetter(
         console.error('[CookieFile] Watch error:', error.message);
       }
     );
+  } else if (debug) {
+    console.log('[CookieFile] File watch disabled');
   }
 
   return () => reader.readCookie();
 }
 
+/**
+ * 自动代理配置选项
+ */
 export interface AutoProxyConfigOptions extends VueProxyConfigOptions {
+  /** 代理目标地址 */
   target: string;
+  /** 忽略的路径列表（不代理这些路径） */
   ignorePaths?: string[];
+  /** 包含的路径列表（只代理这些路径） */
   includePaths?: string[];
+  /** 额外的代理配置 */
   additionalProxies?: Record<string, string>;
 }
 
+/**
+ * 创建自动代理配置
+ * 
+ * 根据配置自动生成 Vue CLI 代理配置对象，支持忽略路径和包含路径两种模式。
+ * 
+ * @param options - 配置选项
+ * @returns Vue CLI 代理配置对象映射
+ */
 export function createAutoProxyConfig(options: AutoProxyConfigOptions): Record<string, ProxyConfig> {
   const { target, ignorePaths = [], includePaths = [], additionalProxies = {}, getCookie, debug, headers } = options;
 

package/src/utils/cookie-reader.ts

@@ -1,39 +1,102 @@
+/**
+ * Cookie 文件读取器模块
+ * 
+ * 提供从文件读取 Cookie 的功能，支持注释过滤和自动文件创建。
+ * 
+ * @module cookie-reader
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 
+/**
+ * Cookie 读取器配置选项
+ */
 export interface CookieReaderOptions {
   cookieFile: string;
   encoding?: BufferEncoding;
 }
 
+/**
+ * Cookie 文件读取器类
+ * 
+ * 提供从文件读取 Cookie 的功能，支持注释过滤和自动文件创建。
+ */
 export class CookieReader {
+  /** 配置选项 */
   protected options: CookieReaderOptions;
+  /** 是否启用调试模式 */
+  protected debug: boolean;
 
-  constructor(options: CookieReaderOptions) {
+  /**
+   * 构造函数
+   * @param options - 配置选项
+   * @param debug - 是否启用调试模式
+   */
+  constructor(options: CookieReaderOptions, debug: boolean = false) {
     this.options = {
       encoding: 'utf-8',
       ...options,
     };
+    this.debug = debug;
   }
 
+  /**
+   * 读取 Cookie 文件内容
+   * 
+   * 支持过滤注释行（以 # 开头）和空行，将有效行用分号连接。
+   * 
+   * @returns Cookie 字符串
+   */
   readCookie(): string {
     try {
       const filePath = path.resolve(this.options.cookieFile);
+      
+      if (this.debug) {
+        console.log('[CookieReader] Resolved cookie file path:', filePath);
+        console.log('[CookieReader] File exists:', fs.existsSync(filePath));
+      }
+      
       if (fs.existsSync(filePath)) {
         const content = fs.readFileSync(filePath, this.options.encoding || 'utf-8');
+        
+        if (this.debug) {
+          console.log('[CookieReader] File content length:', content.length);
+        }
+        
         // 过滤注释行（以 # 开头）和空行，然后合并成一行
         const lines = content.split('\n');
         const cookieLines = lines
           .map(line => line.trim())
           .filter(line => line && !line.startsWith('#'));
-        return cookieLines.join('; ');
+        
+        const result = cookieLines.join('; ');
+        
+        if (this.debug) {
+          console.log('[CookieReader] Parsed cookie:', result ? '(has cookie)' : '(empty)');
+        }
+        
+        return result;
+      }
+      
+      if (this.debug) {
+        console.log('[CookieReader] Cookie file not found:', filePath);
       }
+      
       return '';
-    } catch {
+    } catch (err) {
+      if (this.debug) {
+        console.error('[CookieReader] Error reading cookie file:', (err as Error).message);
+      }
       return '';
     }
   }
 
+  /**
+   * 确保 Cookie 文件存在
+   * 
+   * 如果文件不存在，会自动创建空文件。
+   * 如果父目录不存在，会自动创建目录。
+   */
   ensureCookieFile(): void {
     const filePath = path.resolve(this.options.cookieFile);
     const dir = path.dirname(filePath);
@@ -48,6 +111,14 @@ export class CookieReader {
   }
 }
 
+/**
+ * 创建 Cookie 获取器函数
+ * 
+ * 返回一个函数，每次调用时从文件读取最新的 Cookie 值。
+ * 
+ * @param cookieFile - Cookie 文件路径
+ * @returns Cookie 获取函数
+ */
 export function createCookieGetter(cookieFile: string): () => string {
   const reader = new CookieReader({ cookieFile });
   return () => reader.readCookie();

package/src/utils/cookie-watcher.ts

@@ -1,8 +1,19 @@
+/**
+ * Cookie 文件监听器模块
+ * 
+ * 使用 chokidar 监听 Cookie 文件变化，当文件内容改变时触发回调。
+ * 支持自动创建文件和稳定性阈值配置。
+ * 
+ * @module cookie-watcher
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import chokidar, { FSWatcher } from 'chokidar';
 import { CookieReader } from './cookie-reader';
 
+/**
+ * Cookie 监听器配置选项
+ */
 export interface CookieWatcherOptions {
   cookieFile: string;
   onCookieChange: (cookie: string) => void;
@@ -10,12 +21,26 @@ export interface CookieWatcherOptions {
   autoCreateFile?: boolean;
 }
 
+/**
+ * Cookie 文件监听器类
+ * 
+ * 使用 chokidar 监听 Cookie 文件变化，当文件内容改变时触发回调。
+ * 支持自动创建文件和稳定性阈值配置。
+ */
 export class CookieWatcher {
+  /** 文件监听器实例 */
   private watcher: FSWatcher | null = null;
+  /** 配置选项 */
   private options: CookieWatcherOptions;
+  /** Cookie 读取器 */
   private cookieReader: CookieReader;
+  /** 上次读取的 Cookie 内容 */
   private lastContent: string = '';
 
+  /**
+   * 构造函数
+   * @param options - 配置选项
+   */
   constructor(options: CookieWatcherOptions) {
     this.options = {
       autoCreateFile: true,
@@ -24,6 +49,11 @@ export class CookieWatcher {
     this.cookieReader = new CookieReader({ cookieFile: options.cookieFile });
   }
 
+  /**
+   * 文件变化处理函数
+   * 
+   * 读取新的 Cookie 内容，如果与上次不同则触发回调。
+   */
   private handleChange = (): void => {
     const newContent = this.cookieReader.readCookie();
     if (newContent !== this.lastContent) {
@@ -33,6 +63,9 @@ export class CookieWatcher {
     }
   };
 
+  /**
+   * 启动文件监听
+   */
   start(): void {
     if (this.options.autoCreateFile) {
       this.cookieReader.ensureCookieFile();
@@ -52,7 +85,8 @@ export class CookieWatcher {
         },
       });
 
-      // "add" covers atomic replace (unlink + rename) used by some editors; "change" covers in-place writes
+      // "add" covers atomic replace (unlink + rename) used by some editors; 
+      // "change" covers in-place writes
       this.watcher.on('change', this.handleChange);
       this.watcher.on('add', this.handleChange);
       this.watcher.on('error', (error) => {
@@ -63,6 +97,9 @@ export class CookieWatcher {
     }
   }
 
+  /**
+   * 停止文件监听
+   */
   stop(): void {
     if (this.watcher) {
       this.watcher.close();
@@ -71,11 +108,23 @@ export class CookieWatcher {
     }
   }
 
+  /**
+   * 获取当前 Cookie 值
+   * @returns 当前 Cookie 字符串
+   */
   getCurrentCookie(): string {
     return this.lastContent;
   }
 }
 
+/**
+ * 创建并启动 Cookie 文件监听器
+ * 
+ * @param cookieFile - Cookie 文件路径
+ * @param onCookieChange - Cookie 变化回调函数
+ * @param onError - 错误回调函数（可选）
+ * @returns CookieWatcher 实例
+ */
 export function watchCookieFile(
   cookieFile: string,
   onCookieChange: (cookie: string) => void,

package/src/utils/env-detector.ts

@@ -0,0 +1,162 @@
+/**
+ * 环境检测工具模块
+ * 
+ * 提供智能环境检测功能，用于判断当前是否为生产构建环境，
+ * 从而决定是否启用文件监听等开发环境特性。
+ * 
+ * @module env-detector
+ */
+
+/**
+ * 判断环境变量值是否表示生产环境
+ * 
+ * @param value - 环境变量值
+ * @returns 是否为生产环境值
+ */
+export function isProductionValue(value: string): boolean {
+  const productionValues = [
+    'production', // 生产环境
+    'prod', // 生产环境
+    'prd', // 生产环境
+    'release', // 发布环境
+    'staging', // 预发布环境
+    'uat', // 预发布环境
+  ];
+  return productionValues.includes(value.toLowerCase().trim());
+}
+
+/**
+ * 智能检测当前是否为生产构建环境
+ * 通过多种方式综合判断，避免依赖单一环境变量
+ * 
+ * @param customEnvs 用户自定义的环境变量名称列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀，用于区分不同模块
+ * @returns 是否为生产环境
+ */
+export function detectProductionEnvironment(
+  customEnvs: string[] = [],
+  debug: boolean = false,
+  loggerPrefix: string = '[env-detector]'
+): boolean {
+  const env = process.env;
+  
+  // 1. 检查自定义环境变量
+  if (customEnvs.length > 0) {
+    for (const envName of customEnvs) {
+      const envValue = env[envName];
+      if (envValue && isProductionValue(envValue)) {
+        if (debug) {
+          console.log(`${loggerPrefix} Detected production via custom env: ${envName}=${envValue}`);
+        }
+        return true;
+      }
+    }
+  }
+
+  // 2. 检查常见的环境变量
+  const commonEnvNames = [
+    'NODE_ENV',
+    'BUILD_MODE',
+    'VUE_APP_ENV',
+    'VITE_NODE_ENV',
+    'WEBPACK_MODE',
+    'CI_ENV',
+    'APP_ENV',
+    'ENV',
+    'DEPLOY_ENV',
+    'RUN_MODE',
+  ];
+
+  for (const envName of commonEnvNames) {
+    const envValue = env[envName];
+    if (envValue && isProductionValue(envValue)) {
+      if (debug) {
+        console.log(`${loggerPrefix} Detected production via env: ${envName}=${envValue}`);
+      }
+      return true;
+    }
+  }
+
+  // 3. 检查 CI/CD 环境标识
+  if (env.CI === 'true' || env.CI === '1' || env.CI === 'yes') {
+    if (debug) {
+      console.log(`${loggerPrefix} Detected production via CI env`);
+    }
+    return true;
+  }
+
+  // 4. 检查 npm 生命周期事件（构建命令）
+  if (env.npm_lifecycle_event) {
+    const lifecycleEvent = env.npm_lifecycle_event.toLowerCase();
+    if (lifecycleEvent.includes('build') || 
+        lifecycleEvent.includes('prod') || 
+        lifecycleEvent.includes('prd') ||
+        lifecycleEvent.includes('release')) {
+      if (debug) {
+        console.log(`${loggerPrefix} Detected production via lifecycle event: ${env.npm_lifecycle_event}`);
+      }
+      return true;
+    }
+  }
+
+  // 5. 检查进程参数（构建工具通常会传入特定参数）
+  const processArgs = process.argv.join('').toLowerCase();
+  if (processArgs.includes('build') || 
+      processArgs.includes('production') ||
+      processArgs.includes('--mode=production') ||
+      processArgs.includes('--prod') ||
+      processArgs.includes('--release')) {
+    if (debug) {
+      console.log(`${loggerPrefix} Detected production via process arguments`);
+    }
+    return true;
+  }
+
+  // 默认认为是开发环境
+  return false;
+}
+
+/**
+ * 判断是否应该启用文件监听
+ * 
+ * 注意：此函数仅在 isDev 参数未设置时调用，用于智能判断环境
+ * 如果用户已通过 isDev 参数明确指定环境，则不会调用此函数
+ * 
+ * @param watch 用户设置的 watch 选项
+ * @param customEnvs 用户自定义的环境变量列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀
+ * @returns 是否应该启用监听
+ */
+export function shouldEnableWatch(
+  watch: boolean | 'auto',
+  customEnvs: string[] = [],
+  debug: boolean = false,
+  loggerPrefix: string = '[env-detector]'
+): boolean {
+  // 用户显式设置为 true 或 false，直接返回
+  if (typeof watch === 'boolean') {
+    if (debug && !watch) {
+      console.log(`${loggerPrefix} Watch disabled by user setting`);
+    }
+    return watch;
+  }
+
+  // 'auto' 模式：智能检测环境
+  const isProduction = detectProductionEnvironment(customEnvs, debug, loggerPrefix);
+  
+  if (isProduction) {
+    if (debug) {
+      console.log(`${loggerPrefix} Auto-detected production mode - disabling watch`);
+    }
+    return false;
+  }
+  
+  // 开发环境：启用监听
+  if (debug) {
+    console.log(`${loggerPrefix} Auto-detected development mode - enabling watch`);
+  }
+  
+  return true;
+}

package/src/utils/index.ts

@@ -1,2 +1,10 @@
+/**
+ * 工具模块导出文件
+ * 
+ * 包含 Cookie 读取、文件监听和环境检测等核心工具函数。
+ * 
+ * @module utils
+ */
 export * from './cookie-reader';
-export * from './cookie-watcher';
+export * from './cookie-watcher';
+export * from './env-detector';

package/src/proxy/vite-adapter.ts

@@ -1,77 +0,0 @@
-import type { Plugin } from 'vite';
-import { viteAutoProxyCookie, type ViteAutoProxyCookiePluginOptions } from './vite-plugin';
-import { viteDevProxyCookie, type ViteDevProxyCookieOptions } from './vite-cookie-plugin';
-
-let viteVersion: string = '';
-let majorVersion: number | null = null;
-
-function detectViteVersion(): number {
-  if (majorVersion !== null) {
-    return majorVersion;
-  }
-
-  try {
-    const pkg = require('vite/package.json');
-    viteVersion = pkg.version;
-    majorVersion = parseInt(viteVersion.split('.')[0], 10);
-  } catch {
-    majorVersion = 5;
-  }
-
-  return majorVersion;
-}
-
-export interface UnifiedProxyCookieOptions {
-  cookieFile: string;
-  target?: string;
-  debug?: boolean;
-  autoRestart?: boolean;
-  restartMarkerFile?: string;
-  proxyMap?: Record<string, string>;
-  ignorePaths?: string[];
-  includePaths?: string[];
-  onCookieChange?: (cookie: string) => void;
-  mode?: 'auto' | 'proxy' | 'cookie';
-}
-
-export function createDevProxyCookie(options: UnifiedProxyCookieOptions): Plugin {
-  const {
-    mode = 'auto',
-    ...restOptions
-  } = options;
-
-  const version = detectViteVersion();
-  
-  if (options.debug) {
-    console.log(`[dev-proxy-cookie] Detected Vite ${version}.x`);
-  }
-
-  if (mode === 'cookie' || (mode === 'auto' && !options.target)) {
-    return viteDevProxyCookie({
-      cookieFile: options.cookieFile,
-      debug: options.debug,
-      onCookieChange: options.onCookieChange,
-    });
-  }
-
-  const pluginOptions: ViteAutoProxyCookiePluginOptions = {
-    cookieFile: options.cookieFile,
-    target: options.target!,
-    debug: options.debug,
-    autoRestart: options.autoRestart ?? true,
-    restartMarkerFile: options.restartMarkerFile,
-    proxyMap: options.proxyMap,
-    ignorePaths: options.ignorePaths,
-  };
-
-  return viteAutoProxyCookie(pluginOptions);
-}
-
-export function getViteVersion(): string | null {
-  detectViteVersion();
-  return viteVersion;
-}
-
-export function getViteMajorVersion(): number {
-  return detectViteVersion();
-}