@gylautorun/dev-proxy-cookie 1.0.0 → 1.0.1

package/README.md

@@ -239,11 +239,32 @@ export default defineConfig({
 
 ```javascript
 const getCookie = createFileCookieGetter('./cookie.txt', {
-  watch: true,   // 是否监听文件变化，默认 false
+  watch: true,   // 是否监听文件变化，默认 'auto'
   debug: true,   // 是否输出调试日志，默认 false
+  isDev: process.env.NODE_ENV === 'development',  // 是否为开发环境（优先级最高）
 });
 ```
 
+**选项：**
+
+- `cookieFile` (string): Cookie 文件路径（必需）
+- `watch` (boolean | 'auto'): 是否监听文件变化，默认 `'auto'`
+  - `true`: 始终监听
+  - `false`: 从不监听
+  - `'auto'`: 根据环境自动判断（默认）
+- `debug` (boolean): 是否输出调试日志，默认 `false`
+- `productionEnvs` (string[]): 自定义生产环境变量列表，用于判断是否禁用监听
+- `isDev` (boolean): 是否为开发环境（优先级最高）
+  - 设置此参数后，将直接决定是否启用文件监听
+  - `true`: 启用监听（开发模式）
+  - `false`: 禁用监听（生产模式）
+
+**参数优先级：**
+
+```
+isDev (最高) → watch (中等) → 智能检测 (最低)
+```
+
 ### Vite 相关
 
 #### viteAutoProxyCookie(options)
@@ -265,6 +286,10 @@ Vite 插件，自动配置代理和 Cookie 注入。
 - `includePaths` (string[]): 只代理这些路径
 - `ignorePaths` (array): 忽略的路径
 - `hooks` (object): 钩子函数配置
+- `isDev` (boolean): 是否为开发环境（优先级最高）
+  - 设置此参数后，将直接决定是否启用文件监听
+  - `true`: 启用监听（开发模式）
+  - `false`: 禁用监听（生产模式）
 
 #### viteDevProxyCookie(options)
 
@@ -275,6 +300,14 @@ Vite 插件，基础 Cookie 注入功能。
 - `cookieFile` (string): Cookie 文件路径（必需）
 - `debug` (boolean): 是否开启调试日志，默认 `false`
 - `onCookieChange` ((cookie: string) => void): Cookie 变化回调
+- `watch` (boolean | 'auto'): 是否监听文件变化，默认 `'auto'`
+  - `true`: 始终监听
+  - `false`: 从不监听
+  - `'auto'`: 根据环境自动判断（默认）
+- `isDev` (boolean): 是否为开发环境（优先级最高）
+  - 设置此参数后，将直接决定是否启用文件监听
+  - `true`: 启用监听（开发模式）
+  - `false`: 禁用监听（生产模式）
 
 ### 工具类
 
@@ -458,6 +491,8 @@ src/
 
 ## 最佳实践
 
+### 推荐配置
+
 ```javascript
 // cookie.txt - 存放登录后的 Cookie
 session-id=abc123
@@ -475,7 +510,10 @@ module.exports = {
   devServer: {
     proxy: createAutoProxyConfig({
       target: 'http://localhost:3000',
-      getCookie: createFileCookieGetter('./cookie.txt', { watch: true }),
+      getCookie: createFileCookieGetter('./cookie.txt', { 
+        watch: 'auto',  // 自动判断环境
+        debug: true,
+      }),
       ignorePaths: ['/assets/', '/public/'],
     }),
   },
@@ -489,12 +527,51 @@ export default defineConfig({
     viteAutoProxyCookie({
       cookieFile: './cookie.txt',
       target: 'http://localhost:3000',
+      isDev: process.env.NODE_ENV === 'development',  // 显式指定环境
       ignorePaths: ['/assets/', '/public/'],
     }),
   ],
 });
 ```
 
+### 环境配置建议
+
+**开发环境（推荐使用 `isDev`）**
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  isDev: process.env.NODE_ENV === 'development',
+  debug: true,
+});
+```
+
+**预发布环境（需要调试）**
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  isDev: true,  // 强制启用监听
+  debug: true,
+});
+```
+
+**生产环境（禁用监听）**
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  isDev: false,  // 强制禁用监听
+  debug: false,
+});
+```
+
+**自动检测（默认行为）**
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  watch: 'auto',  // 默认值，自动判断环境
+  debug: true,
+});
+```
+
 ## 常见问题
 
 ### Q: Cookie 文件修改后没有生效？
@@ -522,10 +599,145 @@ A: Cookie 值会被自动处理，支持包含 `/`、`+`、`=` 等特殊字符
 
 A: 启用 `debug: true` 选项，控制台会输出详细的代理日志。也可以在 `hooks.onProxyReq` 中添加自定义日志。
 
+### Q: 构建完成后进程不退出，一直挂起？
+
+A: 这是由于文件监听器在生产环境下仍然运行导致的。解决方案：
+
+**方案一：使用 `isDev` 参数（推荐）**
+
+```javascript
+// Vue CLI 项目
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  isDev: process.env.NODE_ENV === 'development',
+  debug: true,
+});
+
+// Vite 项目
+export default defineConfig({
+  plugins: [
+    viteDevProxyCookie({
+      cookieFile: './cookie.txt',
+      isDev: process.env.NODE_ENV === 'development',
+    }),
+  ],
+});
+```
+
+**方案二：设置 `watch: false`**
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  watch: false,  // 禁用文件监听
+});
+```
+
+**方案三：使用智能检测（默认行为）**
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  watch: 'auto',  // 默认值，自动判断环境
+});
+```
+
+智能检测会检查以下环境变量：
+
+- `NODE_ENV`、`BUILD_MODE`、`VUE_APP_ENV`、`VITE_NODE_ENV` 等
+- CI/CD 环境标识（`CI`）
+- npm 生命周期事件（如 `build`）
+- 进程参数（如 `--mode=production`）
+
+### Q: 如何在预发布环境（staging/uat）启用文件监听？
+
+A: 预发布环境通常需要调试，建议显式设置 `isDev: true`：
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  isDev: true,  // 强制启用监听
+  debug: true,
+});
+```
+
+或者使用 `watch: true`：
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  watch: true,  // 始终监听
+  debug: true,
+});
+```
+
+### Q: `isDev`、`watch` 和智能检测的优先级是什么？
+
+A: 优先级从高到低：
+
+```
+isDev (最高) → watch (中等) → 智能检测 (最低)
+```
+
+- 如果设置了 `isDev`，直接使用该值
+- 如果 `isDev` 未设置但 `watch` 为 `true` 或 `false`，使用 `watch` 值
+- 如果都未设置或 `watch` 为 `'auto'`，使用智能检测
+
+### Q: 如何自定义生产环境检测？
+
+A: 使用 `productionEnvs` 参数：
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  productionEnvs: ['MY_APP_ENV', 'BUILD_TYPE'],  // 自定义环境变量
+  debug: true,
+});
+```
+
+### Q: ESLint 报错 `import/no-extraneous-dependencies`？
+
+A: 确保在 `.eslintrc.js` 中正确配置：
+
+```javascript
+module.exports = {
+  // ...
+  rules: {
+    'import/no-extraneous-dependencies': ['error', {
+      devDependencies: true,
+      optionalDependencies: false,
+    }],
+  },
+};
+```
+
+### Q: 如何查看当前环境检测的详细信息？
+
+A: 启用 `debug: true` 选项：
+
+```javascript
+const getCookie = createFileCookieGetter('./cookie.txt', {
+  watch: 'auto',
+  debug: true,  // 输出环境检测日志
+});
+```
+
+控制台会输出类似信息：
+
+```
+[env-detector] Auto-detected production mode - disabling watch
+```
+
+或
+
+```
+[env-detector] Auto-detected development mode - enabling watch
+```
+
 ## 发布流程
 
 完整的发布流程文档请查看：[docs/release.md](docs/release.md)
 
+## 问题排查
+
+### 构建进程不退出问题
+
+如果遇到构建完成后进程不退出的问题，请查看详细解决方案：[docs/build-hang-issue.md](docs/build-hang-issue.md)
+
 ## License
 
 MIT License

package/dist/index.d.mts

@@ -34,6 +34,15 @@ interface AutoProxyCookieOptions {
         [header: string]: string;
     };
     hooks?: ProxyHooks;
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare class AutoProxyCookie {
     private options;
@@ -61,6 +70,15 @@ declare function createAutoProxyCookie(options: AutoProxyCookieOptions): AutoPro
 
 interface ViteAutoProxyCookiePluginOptions extends AutoProxyCookieOptions {
     name?: string;
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare function viteAutoProxyCookie(options: ViteAutoProxyCookiePluginOptions): Plugin;
 
@@ -68,19 +86,55 @@ interface ViteDevProxyCookieOptions {
     cookieFile: string;
     debug?: boolean;
     onCookieChange?: (cookie: string) => void;
+    /**
+     * 是否监听文件变化
+     * - true: 始终监听
+     * - false: 从不监听
+     * - 'auto': 根据环境自动判断（默认）
+     * @default 'auto'
+     */
+    watch?: boolean | 'auto';
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare function viteDevProxyCookie(options: ViteDevProxyCookieOptions): Plugin;
 
 /** Options for {@link createFileCookieGetter}. */
 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;
 }
 interface VueProxyConfigOptions {
     getCookie?: () => string;
@@ -122,6 +176,23 @@ interface UnifiedProxyCookieOptions {
     includePaths?: string[];
     onCookieChange?: (cookie: string) => void;
     mode?: 'auto' | 'proxy' | 'cookie';
+    /**
+     * 是否监听文件变化
+     * - true: 始终监听
+     * - false: 从不监听
+     * - 'auto': 根据环境自动判断（默认）
+     * @default 'auto'
+     */
+    watch?: boolean | 'auto';
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare function createDevProxyCookie(options: UnifiedProxyCookieOptions): Plugin;
 declare function getViteVersion(): string | null;
@@ -158,4 +229,36 @@ declare class CookieWatcher {
 }
 declare function watchCookieFile(cookieFile: string, onCookieChange: (cookie: string) => void, onError?: (error: Error) => void): CookieWatcher;
 
-export { type AutoProxyConfigOptions, AutoProxyCookie, type AutoProxyCookieOptions, CookieReader, type CookieReaderOptions, CookieWatcher, type CookieWatcherOptions, type CreateFileCookieGetterOptions, type ErrorCallback, type ProxyConfig, type ProxyHooks, type UnifiedProxyCookieOptions, type ViteAutoProxyCookiePluginOptions, type ViteDevProxyCookieOptions, type VueProxyConfigOptions, createAutoProxyConfig, createAutoProxyCookie, createCookieGetter, createDevProxyCookie, createFileCookieGetter, createVueProxyConfig, getViteMajorVersion, getViteVersion, viteAutoProxyCookie, viteDevProxyCookie, watchCookieFile };
+/**
+ * 环境检测工具函数
+ * 用于智能判断当前是否为生产构建环境
+ */
+/**
+ * 判断环境变量值是否表示生产环境
+ */
+declare function isProductionValue(value: string): boolean;
+/**
+ * 智能检测当前是否为生产构建环境
+ * 通过多种方式综合判断，避免依赖单一环境变量
+ *
+ * @param customEnvs 用户自定义的环境变量名称列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀，用于区分不同模块
+ * @returns 是否为生产环境
+ */
+declare function detectProductionEnvironment(customEnvs?: string[], debug?: boolean, loggerPrefix?: string): boolean;
+/**
+ * 判断是否应该启用文件监听
+ *
+ * 注意：此函数仅在 isDev 参数未设置时调用，用于智能判断环境
+ * 如果用户已通过 isDev 参数明确指定环境，则不会调用此函数
+ *
+ * @param watch 用户设置的 watch 选项
+ * @param customEnvs 用户自定义的环境变量列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀
+ * @returns 是否应该启用监听
+ */
+declare function shouldEnableWatch(watch: boolean | 'auto', customEnvs?: string[], debug?: boolean, loggerPrefix?: string): boolean;
+
+export { type AutoProxyConfigOptions, AutoProxyCookie, type AutoProxyCookieOptions, CookieReader, type CookieReaderOptions, CookieWatcher, type CookieWatcherOptions, type CreateFileCookieGetterOptions, type ErrorCallback, type ProxyConfig, type ProxyHooks, type UnifiedProxyCookieOptions, type ViteAutoProxyCookiePluginOptions, type ViteDevProxyCookieOptions, type VueProxyConfigOptions, createAutoProxyConfig, createAutoProxyCookie, createCookieGetter, createDevProxyCookie, createFileCookieGetter, createVueProxyConfig, detectProductionEnvironment, getViteMajorVersion, getViteVersion, isProductionValue, shouldEnableWatch, viteAutoProxyCookie, viteDevProxyCookie, watchCookieFile };

package/dist/index.d.ts

@@ -34,6 +34,15 @@ interface AutoProxyCookieOptions {
         [header: string]: string;
     };
     hooks?: ProxyHooks;
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare class AutoProxyCookie {
     private options;
@@ -61,6 +70,15 @@ declare function createAutoProxyCookie(options: AutoProxyCookieOptions): AutoPro
 
 interface ViteAutoProxyCookiePluginOptions extends AutoProxyCookieOptions {
     name?: string;
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare function viteAutoProxyCookie(options: ViteAutoProxyCookiePluginOptions): Plugin;
 
@@ -68,19 +86,55 @@ interface ViteDevProxyCookieOptions {
     cookieFile: string;
     debug?: boolean;
     onCookieChange?: (cookie: string) => void;
+    /**
+     * 是否监听文件变化
+     * - true: 始终监听
+     * - false: 从不监听
+     * - 'auto': 根据环境自动判断（默认）
+     * @default 'auto'
+     */
+    watch?: boolean | 'auto';
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare function viteDevProxyCookie(options: ViteDevProxyCookieOptions): Plugin;
 
 /** Options for {@link createFileCookieGetter}. */
 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;
 }
 interface VueProxyConfigOptions {
     getCookie?: () => string;
@@ -122,6 +176,23 @@ interface UnifiedProxyCookieOptions {
     includePaths?: string[];
     onCookieChange?: (cookie: string) => void;
     mode?: 'auto' | 'proxy' | 'cookie';
+    /**
+     * 是否监听文件变化
+     * - true: 始终监听
+     * - false: 从不监听
+     * - 'auto': 根据环境自动判断（默认）
+     * @default 'auto'
+     */
+    watch?: boolean | 'auto';
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
 declare function createDevProxyCookie(options: UnifiedProxyCookieOptions): Plugin;
 declare function getViteVersion(): string | null;
@@ -158,4 +229,36 @@ declare class CookieWatcher {
 }
 declare function watchCookieFile(cookieFile: string, onCookieChange: (cookie: string) => void, onError?: (error: Error) => void): CookieWatcher;
 
-export { type AutoProxyConfigOptions, AutoProxyCookie, type AutoProxyCookieOptions, CookieReader, type CookieReaderOptions, CookieWatcher, type CookieWatcherOptions, type CreateFileCookieGetterOptions, type ErrorCallback, type ProxyConfig, type ProxyHooks, type UnifiedProxyCookieOptions, type ViteAutoProxyCookiePluginOptions, type ViteDevProxyCookieOptions, type VueProxyConfigOptions, createAutoProxyConfig, createAutoProxyCookie, createCookieGetter, createDevProxyCookie, createFileCookieGetter, createVueProxyConfig, getViteMajorVersion, getViteVersion, viteAutoProxyCookie, viteDevProxyCookie, watchCookieFile };
+/**
+ * 环境检测工具函数
+ * 用于智能判断当前是否为生产构建环境
+ */
+/**
+ * 判断环境变量值是否表示生产环境
+ */
+declare function isProductionValue(value: string): boolean;
+/**
+ * 智能检测当前是否为生产构建环境
+ * 通过多种方式综合判断，避免依赖单一环境变量
+ *
+ * @param customEnvs 用户自定义的环境变量名称列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀，用于区分不同模块
+ * @returns 是否为生产环境
+ */
+declare function detectProductionEnvironment(customEnvs?: string[], debug?: boolean, loggerPrefix?: string): boolean;
+/**
+ * 判断是否应该启用文件监听
+ *
+ * 注意：此函数仅在 isDev 参数未设置时调用，用于智能判断环境
+ * 如果用户已通过 isDev 参数明确指定环境，则不会调用此函数
+ *
+ * @param watch 用户设置的 watch 选项
+ * @param customEnvs 用户自定义的环境变量列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀
+ * @returns 是否应该启用监听
+ */
+declare function shouldEnableWatch(watch: boolean | 'auto', customEnvs?: string[], debug?: boolean, loggerPrefix?: string): boolean;
+
+export { type AutoProxyConfigOptions, AutoProxyCookie, type AutoProxyCookieOptions, CookieReader, type CookieReaderOptions, CookieWatcher, type CookieWatcherOptions, type CreateFileCookieGetterOptions, type ErrorCallback, type ProxyConfig, type ProxyHooks, type UnifiedProxyCookieOptions, type ViteAutoProxyCookiePluginOptions, type ViteDevProxyCookieOptions, type VueProxyConfigOptions, createAutoProxyConfig, createAutoProxyCookie, createCookieGetter, createDevProxyCookie, createFileCookieGetter, createVueProxyConfig, detectProductionEnvironment, getViteMajorVersion, getViteVersion, isProductionValue, shouldEnableWatch, viteAutoProxyCookie, viteDevProxyCookie, watchCookieFile };