@gylautorun/dev-proxy-cookie 1.0.0 → 1.0.2

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