zhangqingnan_codeingdocs: add child-process documentation (exec, execfile, fork, spawn)

Electron 中的 `execFile` 方法详解

execFile 是 Electron 通过 Node.js child_process 模块提供的核心方法之一，用于直接执行可执行文件而无需通过 shell 解释器。相比 exec，它更安全、更高效，是执行外部程序的推荐方式。

基本概念与核心区别

与 `exec` 的主要区别

特性	`exec`	`execFile`
执行方式	通过 shell 执行	直接执行可执行文件
安全性	有命令注入风险	更安全，参数与命令分离
性能	需要启动 shell，开销较大	直接执行，性能更好
环境变量	继承 shell 环境	可自定义环境变量
命令语法	支持 shell 特性(管道、重定向等)	仅执行单一可执行文件

基本语法

const { execFile } = require('child_process');

// 基础用法
execFile(file [, args] [, options] [, callback])

使用方法

基础示例（ohos electron）

具体实现

const { app, BrowserWindow, ipcMain, Tray, nativeImage } = require('electron');
const { execFile } = require('child_process');
const path = require('path');

let mainWindow, tray;

function createWindow() {
    tray = new Tray(nativeImage.createFromPath(path.join(__dirname, 'electron_white.png')));
    mainWindow = new BrowserWindow({
        width: 800,
        height: 600,
        webPreferences: {
            nodeIntegration: false,
            contextIsolation: true,
        }
    });
    console.log('electron-demo start');
    mainWindow.loadFile('index.html');
}

app.whenReady().then(() => {
    createWindow();

    app.on('activate',() => {
        if(BrowserWindow.getAllWindow().length === 0) createWindow();
    });

    app.on('window-all-closed', () => {
        if (process.platform !== 'darwin') app.quit();
    });
});

// execFile
console.log('electron-demo 即将开始execFile！' + __dirname);
const child = execFile('ln', ['--help'], (error, stdout, stderr) => {
    if (error) {
        console.error(`execFile error: ${error}`);
        return;
    }
    console.log(`stdout: ${stdout}`);
    console.error(`stderr: ${stderr}`);
});

运行效果

在 Electron 主进程中的典型使用

// main.js
const { execFile } = require('child_process');
const path = require('path');

function convertImage(inputPath, outputPath) {
  return new Promise((resolve, reject) => {
    const converter = path.join(__dirname, 'tools/image-converter');

    execFile(
      converter,
      [inputPath, outputPath, '--quality', '90'],
      { cwd: path.dirname(converter) },
      (error, stdout) => {
        if () return reject(error);
        resolve(stdout);
      }
    );
  });
}

在渲染进程中谨慎使用

// renderer.js (需启用 nodeIntegration)
const { execFile } = require('child_process');

// 必须严格限制可执行文件范围
const allowedPrograms = {
  'image-resizer': '/path/to/validated-program'
};

function safeExec(programName, args) {
  if (!allowedPrograms[programName]) {
    throw new Error('未授权的程序');
  }

  execFile(allowedPrograms[programName], args, (error, stdout) => {
    // 处理结果
  });
}

使用注意事项

1. 安全性强化

绝对路径要求：始终使用绝对路径指定可执行文件

// 错误做法
execFile('convert', [...]); 

// 正确做法
const path = require('path');
execFile(path.resolve('/usr/bin/convert'), [...]);

参数消毒：验证所有传入参数

function sanitizeArgs(args) {
  return args.map(arg => {
    // 移除可能危险的字符
    return arg.replace(/[;&|<>$`]/g, '');
  });
}

2. 跨平台处理

可执行文件扩展名：Windows 需要 .exe

const scriptName = process.platform === 'win32' 
  ? 'convert.exe' 
  : 'convert';

PATH 环境变量：不要依赖系统的 PATH
```
execFile('/full/path/to/program', [...]);
```

3. 资源管理

流处理：大数据量时使用 stdio 管道

execFile('ffmpeg', [...], {
  stdio: ['pipe', 'pipe', 'pipe']
});

内存限制：监控子进程内存使用

const child = execFile('memory-hungry-program', [...]);

setInterval => {
  child.memoryUsage().then(usage => {
    if (usage.rss > 500 * 1024 * 1024) {
      child.kill('SIGTERM');
    }
  });
}, 1000);

最佳实践

1. 封装为 Promise 接口

const { execFile } = require('child_process');
const { promisify } = require('util');

const execFileAsync = promisify(execFile);

async function runSafeExec(file, args, options) {
  try {
    const { stdout, stderr } = await execFileAsync(file, args, options);
    return { ok: true, stdout, stderr };
  } catch (error) {
    return { 
      ok: false, 
      error: {
        code: error.code,
        message: error.message,
        killed: error.killed
      }
    };
  }
}

2. 高级选项配置

execFile('/path/to/program', ['arg1', 'arg2'], {
  // 工作目录
  cwd: '/working/directory',

  // 自定义环境变量
  env: { ...process.env, CUSTOM_ENV: 'value' },

  // 超时控制 (毫秒)
  timeout: 5000,

  // 用户权限
  uid: process.getuid(),
  gid: process.getgid(),

  // 标准IO配置
  stdio: ['ignore', 'pipe', 'pipe'],

  // Windows特定
  windowsHide: true
}, (error, stdout) => {
  // 处理结果
});

3. 大型数据处理策略

const { execFile } = require('child_process');
const fs = require('fs');

// 使用文件流替代缓冲区
const output = fs.createWriteStream('output.txt');
const child = execFile('data-generator', ['--size=1G']);

child.stdout.pipe(output);
child.stderr.pipe(process.stderr);

child.on('exit', (code) => {
  if (code === 0) console.log('数据生成完成');
});

4. 进程生命周期管理

class ManagedProcess {
  constructor(executable) {
    this.child = null;
    this.executable = executable;
  }

  start(args) {
    this.child = execFile(this.executable, args, {
      windowsHide: true
    });

    this.child.on('error', this._handleError);
    this.child.on('exit', this._handleExit);
  }

  stop() {
    if (this.child) {
      this.child.removeAllListeners();
      this.child.kill('SIGTERM');
    }
  }

  _handleError = (error) => {
    console.error('进程错误:', error);
  };

  _handleExit = (code) =>    console.log(`进程，代码: ${code}`);
  };
}

测试验证方法

1. 基本功能测试套件

// test-execfile.js
const { execFile } = require('child_process');
const assert = require('assert');
const path = require('path');

// 测试正常执行
execFile(path.join(__dirname, 'test-script.sh'), ['arg1'], (error, stdout) => {
  assert(!error, '不应返回错误');
  assert(stdout.includes('TEST_OK'), '脚本应返回预期输出');
});

// 测试错误退出码
execFile('false', (error) => {
  assert(error, '应返回错误');
  assert.equal(error.code, 1, '退出码应为1');
});

// 测试参数传递
execFile('echo', ['hello', 'world'], (error, stdout) => {
  assert(stdout.trim() === 'hello world', '参数应正确传递');
});

2. 安全性测试

// security-test.js
const maliciousInput = '; rm -rf /';

execFile('echo', [maliciousInput], (error, stdout) => {
  // 验证恶意输入被作为普通字符串处理
  assert(stdout.trim() === maliciousInput, '不应解释特殊字符');
});

// 测试路径遍历
execFile(path.join('..', '..', 'bin', 'program'), (error) => {
  assert(error, '应拒绝相对路径遍历');
});

3. 性能基准测试

// benchmark.js
const { exec, execFile } = require('child_process');
const { performance } = require('perf_hooks');

const rounds = 100;

function testExec() {
  const start = performance.now();
  exec('echo hello', () => {
    const duration = performance.now() - start;
    console.log(`exec: ${duration.toFixed(2)}ms`);
  });
}

function testExecFile() {
  const start = performance.now();
  execFile('echo', ['hello'], () => {
    const duration = performance.now() - start;
    console.log(`execFile: ${duration.toFixed(2)}ms`);
  });
}

// 执行多轮测试
for (let i = 0; i < rounds; i++) {
  testExec();
  testExecFile();
}

4. 错误条件测试

// error-test.js
// 测试不存在的程序
execFile('non-existent-program', (error) => {
  assert.equal(error.code, 'ENOENT');
});

// 测试权限不足
execFile('/root/protected-program', (error) => {
  assert(error.code === 'EACCES' || error.code === 'EPERM');
});

// 测试超时
execFile('sleep', ['5'], { timeout: 1000 }, (error) => {
  assert(error.killed && error.signal === 'SIGTERM');
});

调试技巧

1. 启用详细日志

const child = execFile('program', [...], {
  stdio: ['inherit', 'pipe', 'pipe']
});

child.stdout.on('data', data => console.log(`STDOUT: ${data}`));
child.stderr.on('data', data => console.error(`STDERR: ${data}`));

child.on('exit', (code, signal) => {
  console.log(`退出 - 代码: ${code}, 信号: ${signal}`);
});

2. 使用调试包装器

function debugExecFile(file, args, options) {
  console.debug('执行:', file, args);
  const start = Date.now();

  const child = execFile(file, args, {
    ...options,
    stdio: ['inherit', 'pipe', 'pipe']
  });

  child.on('exit', (code) => {
    console.debug(`完成 (${Date.now() - start}ms) - 退出码: ${code}`);
  });

  return child;
}

总结

Electron 中的 execFile 是执行外部程序的首选方法，相比 exec 具有以下优势：

更安全：避免 shell 注入风险，参数与命令分离
更高效：省去 shell 解释环节，性能更好
更可控：精细控制执行环境和进程特性

关键实践要点：

始终使用绝对路径
严格验证所有参数
合理配置资源限制(内存、超时等)
实现完善的错误处理
跨平台场景进行充分测试

通过遵循这些准则，可以在 Electron 应用中安全高效地集成各种外部程序和系统工具。

返回子进程目录 | 返回文档首页

Electron 中的 execFile 方法详解