@flun/windows 2.0.10 → 3.0.0

package/CHANGELOG.md

@@ -1,4 +1,13 @@
 # 变更日志
-## [2.0.10] - 2026-05-14 19:27
-### 优化:
-- 内部细节优化;
+## [3.0.0] - 2026-5-28 21:40
+### 破坏性变更
+- 移除 `sudo: { enabled: false }` 配置项，现在内部自动检查 sudo 可用性并默认使用提权方式，不再支持显式关闭。
+
+### 修复
+- 修复 Windows 服务环境下 `os.homedir()` 返回系统目录（如 `C:\Windows\System32\config\systemprofile`）而非当前用户目录的问题
+  现在在生成服务 XML 配置时，会自动将安装服务时的当前用户 `USERPROFILE` 注入到服务进程的环境变量中，使得 `os.homedir()` 正确返回用户目录，从而解决依赖用户目录的证书续期等业务路径错误的问题;
+
+### 优化
+- 简化 `#xml` getter 中的环境变量处理逻辑，自动合并用户自定义的 `env` 配置，仅在未显式设置 `USERPROFILE` 时追加正确的用户目录;
+- 简化内部提权判断逻辑,统一使用 `sudo`作为默认（若可用）, `elevate` 次之作为提权方式。
+- 删除了一些没有使用的导出等一些细节优化;

package/README.md

@@ -66,7 +66,6 @@ const svc = new Service({
   //, logmode: 'rotate'            // 日志模式（'reset', 'roll', 'append'）
   //, execPath: process.execPath   // Node.js可执行文件路径（默认当前Node）
   //, logOnAs: {}                  // 服务运行的用户凭据（'domain'、'account'、'password'和'mungeCredentialsAfterInstall'）
-  //, sudo: {enabled:false}        // 提升权限配置（是否在Windows启用了sudo,默认没有）
   //, env: undefined               // 环境变量（默认:undefined）
   //, logging: null                // 日志配置（默认:mode = 'append', pattern = 'yyyMMdd', sizeThreshold = 10240, keepFiles = 8）
   //, allowServiceLogon: undefined // 允许服务登录（默认undefined）
@@ -108,26 +107,28 @@ const svc1 = new Service({
 
 ### 环境变量设置
 
+`@flun/windows` 会自动向服务进程注入 `USERPROFILE` 环境变量,其值为**安装服务时当前登录用户的主目录**（例如 `C:\Users\你的用户名`;
+这确保了服务中调用 `os.homedir()` 能返回正确的用户目录,即使服务以 `LocalSystem` 等系统账户运;
+
+**你通常不需要手动设置 `USERPROFILE`**,如需添加其他自定义环境变量,可按以下方式：
+
 ```js
 import { Service } from '@flun/windows';
-const svc1 = new Service({
-  ...,          // 基本配置略...
+const svc = new Service({
+  name: 'My Service',
+  script: 'C:\\app\\server.js',
   env: {
-    name: "HOME",
-    value: process.env["USERPROFILE"]
+    MY_CUSTOM_VAR: 'some value',
+    ANOTHER_VAR: 'hello'
   }
 });
-
-// 或多个变量
+// 也支持数组形式
 const svc2 = new Service({
-  ...,          // 基本配置略...
-  env: [{
-    name: "HOME",
-    value: process.env["USERPROFILE"]
-  },{
-    name: "TEMP",
-    value: path.join(process.env["USERPROFILE"],"/temp")
-  }]
+  ...,
+  env: [
+    { name: 'VAR1', value: 'value1' },
+    { name: 'VAR2', value: 'value2' }
+  ]
 });
 ```
 
@@ -154,10 +155,8 @@ svc.logOnAs.domain = 'mydomain.local';
 svc.logOnAs.account = 'username';
 svc.logOnAs.password = 'password';
 svc.logOnAs.mungeCredentialsAfterInstall: true // 默认
-
-// 显示启用 sudo 提权 (注意!!需要在系统中启用了sudo,然后在这里设置为true,才有效)
-svc.sudo.enabled = true;
 ```
+> 💡 **提示**：即使你使用默认的 `LocalSystem` 账户运行服务,`@flun/windows` 也会通过自动注入 `USERPROFILE` 环境变量,使你的应用能够正确获取当前登录用户的目录（例如读取用户目录下的配置文件）;因此,你不需要为了修正 `os.homedir()` 而特意配置 `logOnAs` 账户和密码;
 
 ### 服务卸载
 
@@ -199,7 +198,7 @@ const svc = new Service({
 ### 服务实现原理
 
 使用 [winsw]为每个服务生成独立的 `.exe` 和 `.xml` 配置文件,存储在脚本所在目录的 `daemon` 子文件夹中;服务日志可通过 Windows 事件查看器查看;
-
+此外,服务启动时会自动设置 `USERPROFILE` 环境变量为安装服务时当前用户的用户目录,保证路径相关 API 的行为与预期一致;
 ---
 
 # 事件日志系统
@@ -342,7 +341,7 @@ kill(进程PID, () => {
 
 3. **回调函数未执行**：确保正确传递回调函数,如果不需要回调,可以不传但无法获取执行结果
 
-4. **sudo 函数需要在系统中启用sudo命令**：如果是创建服务实例,还需设置 sudo.enabled为true
+4. **sudo 函数需要在系统中设置并启用sudo**
 
 ## 服务管理常见问题
 

package/index.d.ts

@@ -2,7 +2,7 @@ import { elevate, sudo, isAdminUser, platform } from './lib/binaries.js';
 import { kill, list } from './lib/cmd.js';
 import { Service } from './lib/daemon.js';
 import { EventLogger } from './lib/eventlog.js';
-import { exec, execSync, fork, promisify, path, fs, EventEmitter, isPermissionError, getDirname } from './lib/shared.js';
+import { exec, execSync, fork, promisify, execPromise, path, fs, EventEmitter, isPermissionError, getDirname } from './lib/shared.js';
 import { generateXml, createExe } from './lib/winsw.js';
 
 // =================================== lib/binaries.js ===================================
@@ -70,11 +70,12 @@ declare module './lib/eventlog.js' {
  * path, fs;             // Node.js内置模块,提供文件路径处理、文件系统操作等功能
  * class EventEmitter{}; // Node.js内置模块,提供事件驱动编程的功能,允许对象之间进行事件通信
  * // 自定义函数:
+ * execPromise();        // 基于exec函数的Promise版本,用于执行命令并以Promise方式获取结果
  * isPermissionError();  // 检查错误对象是否表示权限错误的函数,用于判断操作失败是否由于权限不足引起
  * getDirname();         // 获取当前模块目录路径的函数,用于在ES模块环境中替代__dirname变量的功能
  * ```
  * >查看定义:@see {@link exec}、{@link execSync}、{@link fork}、{@link promisify}、{@link path}、{@link fs}、{@link EventEmitter}
- * - 自定义函数:{@link isPermissionError}、{@link getDirname}
+ * - 自定义函数:{@link execPromise}、{@link isPermissionError}、{@link getDirname}
  */
 declare module './lib/shared.js' {
     export * from './lib/shared.js';

package/lib/daemon.js

@@ -1,5 +1,5 @@
-import { exec, execSync, promisify, path, fs, EventEmitter, isPermissionError, getDirname } from './shared.js';
-import { elevate, sudo as binSudo } from './binaries.js';
+import { execSync, execPromise, promisify, path, fs, EventEmitter, isPermissionError, getDirname } from './shared.js';
+import { elevate, sudo } from './binaries.js';
 import { generateXml, createExe } from './winsw.js';
 import { EventLogger } from './eventlog.js';
 
@@ -53,8 +53,6 @@ class Service extends EventEmitter {
    * @param {string|null} [config.logOnAs.password] - 登录密码
    * @param {string} [config.logOnAs.domain] - 域名(默认使用COMPUTERNAME)
    * @param {boolean} [config.logOnAs.mungeCredentialsAfterInstall=true] - 安装后是否混淆凭据
-   * @param {Object} [config.sudo] - 提升权限配置
-   * @param {boolean|null} [config.sudo.enabled] - 是否启用sudo方式提升权限
    * @param {Object} [config.env] - 环境变量配置
    * @param {Object} [config.logging] - 日志配置
    * @param {boolean} [config.allowServiceLogon] - 是否允许服务登录
@@ -88,7 +86,7 @@ class Service extends EventEmitter {
       name, script, maxRetries = null, maxRestarts = 3, stoptimeout = 30, wait = 1, nodeOptions = '--harmony',
       scriptOptions = '', stopparentfirst = false, abortOnError = false, grow = 0.25, logpath = null, logmode = 'rotate',
       description = '', execPath = process.execPath, workingDirectory = process.cwd(),
-      logOnAs = {}, sudo = {}, // 嵌套配置对象
+      logOnAs = {},// 嵌套配置对象
       env, logging, allowServiceLogon,    // 其它配置
     } = config, domain = process.env.COMPUTERNAME;
 
@@ -118,9 +116,6 @@ class Service extends EventEmitter {
       account: undefined, password: null, domain, mungeCredentialsAfterInstall: true, ...logOnAs
     };
 
-    // 提升权限配置
-    this.sudo = { enabled: null, ...sudo };
-
     /** 环境变量配置 */
     this.env = env, this.logging = logging, this.allowServiceLogon = allowServiceLogon;
   }
@@ -151,16 +146,22 @@ class Service extends EventEmitter {
 
   // 生成服务的XML配置
   get #xml() {
-    // 提取需要的属性
     const { script, scriptOptions, name, grow, wait, maxRestarts, abortOnError, stopparentfirst, maxRetries, id, nodeOptions,
-      description, logpath, execPath, logOnAs, workingdirectory, stoptimeout, logmode, env, logging, allowServiceLogon } = this,
-      wrapperArgs = ['--file', script, `--scriptoptions=${scriptOptions}`, '--log', `${name} 包装器`, '--grow', grow, '--wait', wait,
-        '--maxrestarts', maxRestarts, '--abortonerror', abortOnError ? 'y' : 'n', '--stopparentfirst', stopparentfirst,
-        ...(maxRetries !== null ? ['--maxretries', maxRetries] : [])];
+      description, logpath, execPath, logOnAs, workingdirectory, stoptimeout, logmode, env, logging, allowServiceLogon } = this;
+
+    // 构建环境变量数组,自动添加 USERPROFILE（如果未显式设置）
+    let envList = [];
+    if (env) envList.push(...(Array.isArray(env) ? env : [env]));
+    if (process.env.USERPROFILE && !envList.some(e => e.name === 'USERPROFILE'))
+      envList.push({ name: 'USERPROFILE', value: process.env.USERPROFILE });
+
+    const wrapperArgs = ['--file', script, `--scriptoptions=${scriptOptions}`, '--log', `${name} 包装器`, '--grow', grow, '--wait', wait,
+      '--maxrestarts', maxRestarts, '--abortonerror', abortOnError ? 'y' : 'n', '--stopparentfirst', stopparentfirst,
+      ...(maxRetries !== null ? ['--maxretries', maxRetries] : [])];
 
     return generateXml({
       name, id, nodeOptions, script: wrapper, scriptOptions, wrapperArgs, description, logpath, execPath, logOnAs, workingdirectory,
-      stopparentfirst, stoptimeout, logmode, env, logging, allowServiceLogon
+      stopparentfirst, stoptimeout, logmode, env: envList, logging, allowServiceLogon
     });
   }
 
@@ -398,12 +399,18 @@ class Service extends EventEmitter {
    * @returns {Promise<{stdout: string, stderr: string}>}
    */
   async #execute(cmd, options = {}) {
+    // 检查 sudo 是否启用,并根据可用性选择提升方法
+    const isSudoAvailableOnWindows = async () => {
+      try {
+        await execPromise('sudo --version', { shell: true });
+        return true;
+      } catch { return false }
+    }, sudoAvailable = await isSudoAvailableOnWindows(), executor = sudoAvailable ? sudo : elevate;
+
     return new Promise((resolve, reject) => {
-      // 检查sudo是否为真
-      const executor = this.sudo.enabled ? (cmd, opts, cb) => binSudo(cmd, opts, cb) : elevate;
       executor(cmd, { ...options, shell: true, windowsHide: true }, (error, stdout, stderr) => {
         if (error) {
-          if (isPermissionError(error.message)) reject(new Error('权限被拒绝, 请以管理员身份重新运行此脚本;'));
+          if (isPermissionError(error.message)) reject(new Error('权限被拒绝,请以管理员身份重新运行此脚本;'));
           else console.error(error.toString()), reject(error);
         }
         else resolve({ stdout, stderr });

package/lib/eventlog.js

@@ -1,8 +1,7 @@
-import { exec, execSync, promisify, isPermissionError } from './shared.js';
+import { execPromise, execSync, isPermissionError } from './shared.js';
 import { elevate } from './binaries.js';
 
-const execAsync = promisify(exec),
-  eventLogs = ['APPLICATION', 'SYSTEM', 'SECURITY'], validTypes = ['ERROR', 'WARNING', 'INFORMATION', 'SUCCESSAUDIT', 'FAILUREAUDIT'];
+const eventLogs = ['APPLICATION', 'SYSTEM', 'SECURITY'], validTypes = ['ERROR', 'WARNING', 'INFORMATION', 'SUCCESSAUDIT', 'FAILUREAUDIT'];
 
 /**
  * 事件日志记录器类,用于向Windows事件查看器写入日志
@@ -136,7 +135,7 @@ class EventLogger {
 
     // 执行命令
     try {
-      await execAsync(command), callback?.();
+      await execPromise(command), callback?.();
     } catch (error) {
       if (isPermissionError(error?.message)) await this.#elevateCommand(command, callback);
       else {

package/lib/shared.js

@@ -9,6 +9,13 @@ import fs from 'fs';
 import { EventEmitter } from 'events';
 import { fileURLToPath } from 'url';
 
+/**
+ * 将 child_process.exec 包装成 Promise
+ * >查看定义:@see {@link execPromise}
+ * @type {function(string, Object): Promise<{ stdout: string, stderr: string }>}
+ */
+const execPromise = promisify(exec);
+
 /**
  * 检查错误是否为权限不足的错误
  * >查看定义:@see {@link isPermissionError}
@@ -31,4 +38,4 @@ const isPermissionError = error => {
  */
 const getDirname = metaUrl => path.dirname(fileURLToPath(metaUrl));
 
-export { exec, execSync, fork, promisify, path, fs, EventEmitter, isPermissionError, getDirname };
+export { exec, execSync, fork, execPromise, promisify, path, fs, EventEmitter, isPermissionError, getDirname };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flun/windows",
-  "version": "2.0.10",
+  "version": "3.0.0",
   "description": "支持 Windows 服务、事件日志、UAC 以及多种与操作系统交互的辅助方法",
   "keywords": [
     "windows",

package/sevWin.js

@@ -7,7 +7,6 @@ const serviceName = 'TestApp', scriptPath = 'D:\\test\\dev.js', // 请根据实
 		script: scriptPath,
 		nodeOptions: ['--harmony', '--max-old-space-size=4096'],
 		env: { name: "NODE_ENV", value: "production" },
-		// sudo: { enabled: true }
 	});
 
 const installService = () => {