@gylautorun/dev-proxy-cookie 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gylautorun/dev-proxy-cookie",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "开发环境代理Cookie注入工具，支持文件监听自动重载和自动代理",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -1,2 +1,15 @@
+/**
+ * dev-proxy-cookie 模块入口文件
+ * 
+ * 提供开发环境下的 Cookie 代理和文件监听功能，支持 Vue CLI 和 Vite 构建工具。
+ * 
+ * 主要功能：
+ * - Cookie 文件读取与监听
+ * - 代理请求时自动注入 Cookie
+ * - 支持 Vue CLI 和 Vite 两种构建工具
+ * - 智能环境检测，自动启用/禁用文件监听
+ * 
+ * @module dev-proxy-cookie
+ */
 export * from './proxy';
 export * from './utils';

package/src/proxy/apply-dev-cookie-header.ts

@@ -1,14 +1,44 @@
 /**
- * Replace outbound Cookie with the dev file cookie.
- * Browsers send `Cookie` when `withCredentials` is true; merging with file cookie often yields duplicate
- * names (e.g. two JSESSIONID) and many servers honor the first value — the stale browser session.
+ * 应用开发环境 Cookie 到代理请求头
+ * 
+ * 将文件中读取的 Cookie 设置到代理请求中，替换浏览器发送的 Cookie。
+ * 这是必要的，因为当 withCredentials 为 true 时，浏览器会发送其自身的 Cookie，
+ * 与文件中的 Cookie 合并可能导致重复的 Cookie 名称（如两个 JSESSIONID），
+ * 而服务器通常会优先使用第一个值（浏览器的旧会话）。
+ * 
+ * @param proxyReq - 代理请求对象
+ * @param cookie - 要设置的 Cookie 字符串
  */
 export function applyDevCookieHeader(
-  proxyReq: { removeHeader(name: string): void; setHeader(name: string, value: string): void },
+  proxyReq: { removeHeader(name: string): void; setHeader(name: string, value: string): void; getHeader?(name: string): string | undefined },
   cookie: string
 ): void {
-  if (!cookie) return;
+  console.log('[applyDevCookieHeader] === START ===');
+  console.log('[applyDevCookieHeader] Cookie to apply:', cookie ? `(length: ${cookie.length})` : '(empty)');
+  
+  if (!cookie) {
+    console.log('[applyDevCookieHeader] Cookie is empty, returning');
+    console.log('[applyDevCookieHeader] === END ===');
+    return;
+  }
+  
+  // 尝试获取当前的 cookie 头（如果有）
+  const existingCookie = proxyReq.getHeader?.('Cookie');
+  console.log('[applyDevCookieHeader] Cookie current:', existingCookie ? `(length: ${String(existingCookie).length})` : '(none)');
+  
+  // 如果现有 Cookie 与要设置的 Cookie 相同，直接跳过处理
+  if (existingCookie === cookie) {
+    console.log('[applyDevCookieHeader] Cookie is already set, skipping');
+    console.log('[applyDevCookieHeader] === END ===');
+    return;
+  }
+  
   proxyReq.removeHeader('cookie');
   proxyReq.removeHeader('Cookie');
   proxyReq.setHeader('Cookie', cookie);
+  
+  // 验证是否设置成功
+  const newCookie = proxyReq.getHeader?.('Cookie');
+  console.log('[applyDevCookieHeader] Cookie new:', newCookie ? `(length: ${String(newCookie).length})` : '(failed)');
+  console.log('[applyDevCookieHeader] === END ===');
 }

package/src/proxy/core.ts

@@ -1,3 +1,11 @@
+/**
+ * 自动代理 Cookie 核心模块
+ * 
+ * 提供完整的开发环境代理解决方案，支持 HTTP 和 WebSocket 代理，
+ * 自动从文件读取 Cookie 并注入到代理请求中。
+ * 
+ * @module core
+ */
 import * as http from 'http';
 import * as net from 'net';
 import * as fs from 'fs';
@@ -8,6 +16,12 @@ import httpProxy from 'http-proxy';
 import { CookieReader, CookieWatcher, watchCookieFile } from '../utils';
 import { applyDevCookieHeader } from './apply-dev-cookie-header';
 
+/**
+ * 错误回调函数类型
+ * @param err - 错误对象
+ * @param req - 请求对象
+ * @param res - 响应对象或 Socket
+ */
 export type ErrorCallback = (err: Error, req: IncomingMessage, res: ServerResponse | net.Socket) => void;
 
 interface ProxyServer {
@@ -48,6 +62,12 @@ export interface AutoProxyCookieOptions {
   autoRestart?: boolean;
   restartMarkerFile?: string;
   proxyMap?: Record<string, string>;
+  /**
+   * 需要代理的路径前缀列表（默认代理到 target）
+   * 例如: ['/api', '/digital-platform']
+   * 如果请求路径匹配这些前缀之一，将被代理到 target
+   */
+  proxyPaths?: string[];
   ignorePaths?: string[];
   ws?: boolean;
   changeOrigin?: boolean;
@@ -60,16 +80,50 @@ export interface AutoProxyCookieOptions {
   cookiePathRewrite?: false | string | { [oldPath: string]: string };
   headers?: { [header: string]: string };
   hooks?: ProxyHooks;
+  /**
+   * 是否启用文件监听
+   * - 'auto': 自动（如果 isDev 为 true，则启用监听）
+   * - true: 强制启用监听
+   * - false: 禁用监听
+   *
+   * 默认值: 'auto'
+   */
+  watch?: 'auto' | boolean;
+  /**
+   * 是否为开发环境（优先级最高）
+   * 设置此参数后，将直接决定是否启用文件监听：
+   * - true: 启用监听（开发模式）
+   * - false: 禁用监听（生产模式）
+   *
+   * 使用示例: isDev: process.env.NODE_ENV === 'development'
+   */
+  isDev?: boolean;
 }
 
+/**
+ * 自动代理 Cookie 类
+ * 
+ * 提供完整的开发环境代理解决方案，支持 HTTP 和 WebSocket 代理，
+ * 自动从文件读取 Cookie 并注入到代理请求中。
+ */
 export class AutoProxyCookie {
+  /** 合并后的配置选项 */
   private options: AutoProxyCookieOptions & { hooks: Required<ProxyHooks> };
+  /** 当前 Cookie 值 */
   private currentCookie: string = '';
+  /** Vite 开发服务器实例 */
   private server: ViteDevServer | null = null;
+  /** HTTP 代理服务器实例 */
   private proxyServer: ProxyServer | null = null;
+  /** Cookie 文件监听器 */
   private watcher: CookieWatcher | null = null;
+  /** Cookie 文件读取器 */
   private cookieReader: CookieReader;
 
+  /**
+   * 构造函数
+   * @param options - 配置选项
+   */
   constructor(options: AutoProxyCookieOptions) {
     const defaultHooks: Required<ProxyHooks> = {
       onProxyReq: () => {},
@@ -91,6 +145,7 @@ export class AutoProxyCookie {
       autoRestart: false,
       restartMarkerFile: '.cookie-restart-marker',
       proxyMap: {},
+      proxyPaths: [],
       ignorePaths: [],
       ws: true,
       changeOrigin: true,
@@ -104,9 +159,13 @@ export class AutoProxyCookie {
       headers: {},
       ...mergedOptions,
     };
-    this.cookieReader = new CookieReader({ cookieFile: options.cookieFile });
+    this.cookieReader = new CookieReader({ cookieFile: options.cookieFile }, options.debug ?? false);
   }
 
+  /**
+   * Cookie 变化处理函数
+   * @param newCookie - 新的 Cookie 值
+   */
   private handleCookieChange = (newCookie: string): void => {
     if (newCookie !== this.currentCookie) {
       this.currentCookie = newCookie;
@@ -124,19 +183,50 @@ export class AutoProxyCookie {
     }
   };
 
+  /**
+   * 根据请求路径获取代理目标 URL
+   * @param req - HTTP 请求对象
+   * @returns 代理目标 URL
+   */
   private getProxyUrl(req: IncomingMessage): string {
-    const pathname = req.url?.split('?')[0] || '/';
+    const fullUrl = req.url || '/';
+    const pathname = new URL(fullUrl, 'http://localhost').pathname;
     const proxyMap = this.options.proxyMap || {};
+    const proxyPaths = this.options.proxyPaths || [];
 
+    this.log('debug', '[AutoProxyCookie] getProxyUrl - Request path:', pathname);
+    this.log('debug', '[AutoProxyCookie] getProxyUrl - Available proxyMap paths:', Object.keys(proxyMap));
+    this.log('debug', '[AutoProxyCookie] getProxyUrl - Available proxyPaths:', proxyPaths);
+
+    // 首先检查 proxyMap（自定义代理目标）
     for (const [prefix, target] of Object.entries(proxyMap)) {
-      if (pathname.startsWith(prefix)) {
+      const matches = pathname.startsWith(prefix);
+      this.log('debug', '[AutoProxyCookie] getProxyUrl - Checking proxyMap:', prefix, '- matches:', matches);
+      if (matches) {
+        this.log('debug', '[AutoProxyCookie] getProxyUrl - Matched proxyMap:', prefix, '->', target);
         return target;
       }
     }
 
+    // 然后检查 proxyPaths（默认代理到 target）
+    for (const prefix of proxyPaths) {
+      const matches = pathname.startsWith(prefix);
+      this.log('debug', '[AutoProxyCookie] getProxyUrl - Checking proxyPaths:', prefix, '- matches:', matches);
+      if (matches) {
+        this.log('debug', '[AutoProxyCookie] getProxyUrl - Matched proxyPaths:', prefix, '->', this.options.target);
+        return this.options.target;
+      }
+    }
+
+    this.log('debug', '[AutoProxyCookie] getProxyUrl - No match found, using default target:', this.options.target);
     return this.options.target;
   }
 
+  /**
+   * 判断路径是否应该被忽略（不代理）
+   * @param pathname - 请求路径
+   * @returns 是否忽略
+   */
   private isIgnoredPath(pathname: string): boolean {
     const ignorePaths = this.options.ignorePaths || [];
     return ignorePaths.some(ignored =>
@@ -144,9 +234,16 @@ export class AutoProxyCookie {
     );
   }
 
+  /**
+   * 日志输出函数
+   * @param level - 日志级别
+   * @param args - 日志参数
+   */
   private log(level: 'debug' | 'info' | 'warn' | 'error', ...args: any[]): void {
     const levels: Record<string, number> = { debug: 0, info: 1, warn: 2, error: 3 };
-    const currentLevel = levels[this.options.logLevel || 'info'];
+    // 如果设置了 debug: true，则使用 debug 级别
+    const effectiveLogLevel = this.options.debug ? 'debug' : (this.options.logLevel || 'info');
+    const currentLevel = levels[effectiveLogLevel];
     const msgLevel = levels[level];
 
     if (msgLevel >= currentLevel) {
@@ -160,6 +257,11 @@ export class AutoProxyCookie {
     }
   }
 
+  /**
+   * 创建代理服务器配置选项
+   * @param target - 代理目标地址
+   * @returns 代理服务器配置
+   */
   private createProxyOptions(target: string): ServerOptions {
     const {
       ws,
@@ -190,9 +292,24 @@ export class AutoProxyCookie {
     };
   }
 
+  /**
+   * 代理请求处理函数
+   * @param proxyReq - 代理请求对象
+   * @param req - 原始请求对象
+   * @param res - 响应对象
+   * @param _options - 服务器选项
+   */
   private handleOnProxyReq = (proxyReq: any, req: IncomingMessage, res: ServerResponse, _options: ServerOptions): void => {
+    console.log('[AutoProxyCookie] === handleOnProxyReq START ===');
+    console.log('[AutoProxyCookie] Request URL:', req.method, req.url);
+    console.log('[AutoProxyCookie] Current cookie:', this.currentCookie ? `(length: ${this.currentCookie.length})` : '(empty)');
+
     if (this.currentCookie) {
+      console.log('[AutoProxyCookie] Applying cookie header...');
       applyDevCookieHeader(proxyReq, this.currentCookie);
+      console.log('[AutoProxyCookie] Cookie header applied successfully');
+    } else {
+      console.log('[AutoProxyCookie] No cookie to apply - currentCookie is empty!');
     }
 
     this.log('debug', '[AutoProxyCookie] Proxy Request:', req.method, req.url);
@@ -204,8 +321,16 @@ export class AutoProxyCookie {
         this.log('error', '[AutoProxyCookie] onProxyReq hook error:', (err as Error).message);
       }
     }
+    
+    console.log('[AutoProxyCookie] === handleOnProxyReq END ===');
   };
 
+  /**
+   * 代理响应处理函数
+   * @param proxyRes - 代理响应对象
+   * @param req - 原始请求对象
+   * @param res - 响应对象
+   */
   private handleOnProxyRes = (proxyRes: any, req: IncomingMessage, res: ServerResponse): void => {
     const allowedHeaders = [
       'Content-Type',
@@ -233,6 +358,12 @@ export class AutoProxyCookie {
     }
   };
 
+  /**
+   * HTTP 代理错误处理函数
+   * @param err - 错误对象
+   * @param req - 请求对象
+   * @param res - 响应对象或 Socket
+   */
   private handleOnError = (err: Error, req: IncomingMessage, res: ServerResponse | net.Socket): void => {
     this.log('error', '[AutoProxyCookie] Proxy Error:', err.message);
     this.log('error', '[AutoProxyCookie] URL:', req.url);
@@ -255,6 +386,12 @@ export class AutoProxyCookie {
     }
   };
 
+  /**
+   * WebSocket 代理错误处理函数
+   * @param err - 错误对象
+   * @param req - 请求对象
+   * @param socket - WebSocket 连接的 Socket
+   */
   private handleOnWsError = (err: Error, req: IncomingMessage, socket: any): void => {
     this.log('error', '[AutoProxyCookie] WebSocket Proxy Error:', err.message);
     this.log('error', '[AutoProxyCookie] WebSocket URL:', req.url);
@@ -272,6 +409,10 @@ export class AutoProxyCookie {
     }
   };
 
+  /**
+   * 初始化代理中间件
+   * @param server - Vite 开发服务器实例
+   */
   async setup(server: ViteDevServer): Promise<void> {
     this.server = server;
     this.currentCookie = this.cookieReader.readCookie();
@@ -304,30 +445,52 @@ export class AutoProxyCookie {
     }
 
     server.middlewares.use((req: any, res: any, next: any) => {
-      const pathname = new URL(req.url || '/', 'http://localhost').pathname;
+      const fullUrl = req.url || '/';
+      const pathname = new URL(fullUrl, 'http://localhost').pathname;
+      
+      // 始终输出请求信息（不仅仅是 debug 模式）
+      console.log('[AutoProxyCookie] === Incoming Request ===');
+      console.log('[AutoProxyCookie] Method:', req.method);
+      console.log('[AutoProxyCookie] Full URL:', fullUrl);
+      console.log('[AutoProxyCookie] Pathname:', pathname);
+      console.log('[AutoProxyCookie] Headers:', JSON.stringify(req.headers, null, 2));
 
       if (this.isIgnoredPath(pathname)) {
+        console.log('[AutoProxyCookie] Path ignored, passing to next middleware');
         next();
         return;
       }
 
+      // 读取 cookie 并更新 currentCookie
       this.currentCookie = this.cookieReader.readCookie();
+      console.log('[AutoProxyCookie] Current cookie:', this.currentCookie ? `(length: ${this.currentCookie.length})` : '(empty)');
+      if (this.currentCookie) {
+        console.log('[AutoProxyCookie] Cookie preview:', this.currentCookie);
+      }
+
+      // 检查是否匹配代理路径（包括 proxyMap 和 proxyPaths）
+      const proxyMapKeys = Object.keys(this.options.proxyMap || {});
+      const proxyPaths = this.options.proxyPaths || [];
+      const allProxyPrefixes = [...proxyMapKeys, ...proxyPaths];
+      const matched = allProxyPrefixes.some(prefix => pathname.startsWith(prefix));
+      console.log('[AutoProxyCookie] Path matches proxy rules:', matched);
 
       if (this.proxyServer) {
         const target = this.getProxyUrl(req);
-        if (this.options.debug || this.options.logLevel === 'debug') {
-          this.log('info', `[AutoProxyCookie] ${pathname} -> ${target}`);
-        }
+        console.log(`[AutoProxyCookie] Proxying ${req.method} ${pathname} -> ${target}`);
 
         const proxyOptions = this.createProxyOptions(target);
 
         try {
+          console.log('[AutoProxyCookie] Calling proxyServer.web...');
           this.proxyServer.web(req, res, proxyOptions);
+          console.log('[AutoProxyCookie] proxyServer.web called successfully');
         } catch (err: any) {
-          this.log('error', '[AutoProxyCookie] Proxy web error:', err.message);
+          console.error('[AutoProxyCookie] Proxy web error:', err.message);
           next(err);
         }
       } else {
+        console.log('[AutoProxyCookie] No proxy server, passing to next middleware');
         next();
       }
     });
@@ -367,16 +530,43 @@ export class AutoProxyCookie {
     }
   }
 
+  /**
+   * 启动 Cookie 文件监听
+   */
   private startFileWatch(): void {
-    this.watcher = watchCookieFile(
-      this.options.cookieFile,
-      this.handleCookieChange,
-      (error) => {
-        this.log('error', '[AutoProxyCookie] File watch error:', error.message);
+    // 判断是否应该启用监听
+    // isDev 参数优先级最高
+    let shouldWatch: boolean;
+    
+    if (this.options.isDev !== undefined) {
+      shouldWatch = this.options.isDev;
+      if (this.options.debug) {
+        console.log(`[AutoProxyCookie] isDev=${this.options.isDev}, ${shouldWatch ? 'enabling' : 'disabling'} watch`);
       }
-    );
+    } else {
+      // 默认启用监听（因为 AutoProxyCookie 主要用于开发环境）
+      shouldWatch = true;
+      if (this.options.debug) {
+        console.log('[AutoProxyCookie] Default behavior: enabling watch (dev mode)');
+      }
+    }
+    
+    if (shouldWatch) {
+      this.watcher = watchCookieFile(
+        this.options.cookieFile,
+        this.handleCookieChange,
+        (error) => {
+          this.log('error', '[AutoProxyCookie] File watch error:', error.message);
+        }
+      );
+    } else if (this.options.debug) {
+      console.log('[AutoProxyCookie] File watch disabled');
+    }
   }
 
+  /**
+   * 停止代理服务
+   */
   stop(): void {
     if (this.watcher) {
       this.watcher.stop();
@@ -389,11 +579,20 @@ export class AutoProxyCookie {
     this.log('info', '[AutoProxyCookie] Stopped');
   }
 
+  /**
+   * 获取当前 Cookie 值
+   * @returns 当前 Cookie 字符串
+   */
   getCurrentCookie(): string {
     return this.currentCookie;
   }
 }
 
+/**
+ * 创建 AutoProxyCookie 实例
+ * @param options - 配置选项
+ * @returns AutoProxyCookie 实例
+ */
 export function createAutoProxyCookie(options: AutoProxyCookieOptions): AutoProxyCookie {
   return new AutoProxyCookie(options);
 }

package/src/proxy/index.ts

@@ -1,5 +1,10 @@
+/**
+ * 代理模块导出文件
+ * 
+ * 包含 Vue CLI 和 Vite 的代理配置实现，提供完整的开发环境代理解决方案。
+ * 
+ * @module proxy
+ */
 export * from './core';
-export * from './vite-plugin';
-export * from './vite-cookie-plugin';
+export * from './vite-middleware-plugin';
 export * from './vue-proxy-config';
-export * from './vite-adapter';

package/src/proxy/vite-middleware-plugin.ts

@@ -0,0 +1,158 @@
+/**
+ * Vite 中间件代理插件模块
+ * 
+ * 提供基于中间件的 Vite 代理功能，支持自动注入 Cookie。
+ * 此实现使用 http-proxy 直接处理请求，确保 Cookie 正确注入。
+ * 
+ * @module vite-middleware-plugin
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import { CookieReader } from '../utils/cookie-reader';
+
+/**
+ * Vite 中间件代理 Cookie 插件配置选项
+ */
+export interface ViteMiddlewareProxyOptions {
+  /** Cookie 文件路径 */
+  cookieFile: string;
+  /** 默认代理目标地址 */
+  target: string;
+  /** 是否启用调试日志 */
+  debug?: boolean;
+  /** 
+   * 代理路径映射表
+   * 键：路径前缀，值：代理目标地址
+   */
+  proxyMap?: Record<string, string>;
+  /** 
+   * 需要代理的路径前缀列表（使用默认 target）
+   */
+  proxyPaths?: string[];
+  /** 
+   * 需要忽略的路径前缀列表（不代理）
+   */
+  ignorePaths?: string[];
+}
+
+/**
+ * 判断路径是否应该被忽略（不代理）
+ */
+function isIgnoredPath(pathname: string, ignorePaths: string[]): boolean {
+  return ignorePaths.some(ignored => pathname.startsWith(ignored));
+}
+
+/**
+ * 判断路径是否应该被代理
+ */
+function shouldProxy(pathname: string, proxyPrefixes: string[]): boolean {
+  return proxyPrefixes.some(prefix => pathname.startsWith(prefix));
+}
+
+/**
+ * 获取代理目标地址
+ */
+function getProxyTarget(pathname: string, proxyMap: Record<string, string>, defaultTarget: string): string {
+  for (const [prefix, target] of Object.entries(proxyMap)) {
+    if (pathname.startsWith(prefix)) {
+      return target;
+    }
+  }
+  return defaultTarget;
+}
+
+/**
+ * 创建 Vite 中间件代理 Cookie 插件
+ * 
+ * @param options - 插件配置选项
+ * @returns Vite 插件对象
+ */
+export function viteMiddlewareProxy(options: ViteMiddlewareProxyOptions): any {
+  const {
+    cookieFile,
+    target,
+    debug = false,
+    proxyMap = {},
+    proxyPaths = [],
+    ignorePaths = [],
+  } = options;
+
+  // 创建 Cookie 读取器
+  const cookieReader = new CookieReader({ cookieFile }, debug);
+  let currentCookie = cookieReader.readCookie();
+
+  // 合并所有代理路径前缀
+  const allProxyPrefixes = [
+    ...Object.keys(proxyMap),
+    ...proxyPaths,
+  ];
+
+  return {
+    name: 'vite-middleware-proxy',
+    apply: 'serve',
+
+    configureServer(server: any) {
+      // 延迟加载 http-proxy 以避免启动时的兼容性问题
+      const httpProxy = require('http-proxy');
+      const proxyServer = httpProxy.createProxyServer({});
+
+      // 监听 Cookie 文件变化
+      if (debug) {
+        console.log('[ViteMiddlewareProxy] Watching cookie file:', cookieFile);
+      }
+
+      // 添加中间件
+      server.middlewares.use((req: IncomingMessage, res: ServerResponse, next: () => void) => {
+        const pathname = new URL(req.url || '/', 'http://localhost').pathname;
+
+        // 检查是否需要忽略
+        if (isIgnoredPath(pathname, ignorePaths)) {
+          if (debug) {
+            console.log('[ViteMiddlewareProxy] Ignoring:', pathname);
+          }
+          next();
+          return;
+        }
+
+        // 检查是否需要代理
+        if (!shouldProxy(pathname, allProxyPrefixes)) {
+          next();
+          return;
+        }
+
+        // 获取代理目标
+        const proxyTarget = getProxyTarget(pathname, proxyMap, target);
+
+        if (debug) {
+          console.log('[ViteMiddlewareProxy] Proxying:', req.method, pathname, '->', proxyTarget);
+        }
+
+        // 读取最新的 Cookie
+        currentCookie = cookieReader.readCookie();
+
+        // 注入 Cookie
+        if (currentCookie) {
+          if (debug) {
+            console.log('[ViteMiddlewareProxy] Injecting cookie:', `(length: ${currentCookie.length})`);
+          }
+          (req as any).headers['cookie'] = currentCookie;
+          (req as any).headers['Cookie'] = currentCookie;
+        }
+
+        // 代理请求
+        proxyServer.web(req, res, {
+          target: proxyTarget,
+          changeOrigin: true,
+          secure: false,
+          ignorePath: false,
+        });
+      });
+
+      // 错误处理
+      proxyServer.on('error', (err: Error, req: IncomingMessage) => {
+        console.error('[ViteMiddlewareProxy] Proxy error:', err.message, 'for', req.url);
+      });
+    },
+  };
+}
+
+export default viteMiddlewareProxy;