Node.js多文件模块间传递变量的最优方案探讨

嘿，这个场景我太熟悉了——单文件Node.js模块越写越大，想拆分功能却被那些到处被访问修改的顶层变量绊住脚，对吧？别担心，我给你几个实用的解决方案，都是日常开发里验证过的：

这是最直接的过渡方案，适合不想大幅重构原有代码的情况。Node.js模块是单例模式，所以把需要共享的顶层变量抽成单独模块后，所有引入它的文件拿到的都是同一个对象，修改会自动同步。

举个实际例子：
首先创建shared-state.js来存放共享变量：

// shared-state.js
module.exports = {
  logger: null, // 后续初始化的日志实例
  appConfig: {}, // 全局配置
  runtimeState: {} // 其他需要跨模块共享的状态
};

在主模块里完成初始化：

// main.js
const sharedState = require('./shared-state');
const loggerModule = require('./logger');

// 把初始化好的实例赋值到共享状态
sharedState.logger = loggerModule.setupLogger(sharedState.appConfig);
sharedState.appConfig = require('./config');

拆分出去的功能模块直接引入使用：

// logger.js
const sharedState = require('./shared-state');

function logInfo(message) {
  if (sharedState.logger) {
    sharedState.logger.info(`[INFO] ${message}`);
  }
}

module.exports = {
  setupLogger: (config) => { /* 日志初始化逻辑 */ },
  logInfo
};

⚠️ 注意：这种方式虽然简单，但别过度依赖共享状态，不然容易变成隐形全局变量，后期排查问题会很麻烦。

如果想让代码更规范、更易测试，依赖注入是更好的选择。核心思路是：把模块需要的变量/实例作为参数传递进去，而不是让模块自己去“找”共享状态。

比如重构日志模块：

// logger.js
// 先导出创建实例的方法
function createLogger(config) {
  return {
    info: (msg) => console.log(`[INFO] ${msg}`),
    error: (msg) => console.error(`[ERROR] ${msg}`)
  };
}

// 所有需要日志的函数，都把logger作为参数传入
function logUserAction(logger, userId, action) {
  logger.info(`用户${userId}执行了${action}`);
}

module.exports = { createLogger, logUserAction };

主模块里的调用方式：

// main.js
const { createLogger } = require('./logger');
const { processOrder } = require('./order-processor');

const appConfig = require('./config');
const logger = createLogger(appConfig);

// 把logger传递给其他模块的函数
processOrder(logger, orderData);

如果模块里有多个函数需要依赖，也可以给模块加个初始化方法：

// order-processor.js
let logger;

// 初始化时传入依赖
function init(sharedLogger) {
  logger = sharedLogger;
}

function processOrder(orderData) {
  logger.info(`开始处理订单：${orderData.id}`);
  // 业务逻辑...
}

module.exports = { init, processOrder };

然后在主模块里初始化：

// main.js
const { init: initOrderProcessor } = require('./order-processor');
initOrderProcessor(logger);

这种方式的好处是依赖关系一目了然，单元测试时可以轻松mock依赖，避免隐形状态带来的问题，唯一的缺点是需要修改原有函数的调用方式，重构工作量稍大。

如果你的模块功能本来就和某些状态紧密绑定，用类封装是更优雅的选择。把原来的顶层变量作为类的实例属性，相关方法作为类的方法，然后在主模块创建实例，再传递给其他模块使用。

比如：

// app-core.js
class AppCore {
  constructor(config) {
    this.config = config;
    this.logger = this._initLogger();
    this.runtimeState = {};
  }

  // 私有方法做初始化
  _initLogger() {
    return {
      info: (msg) => console.log(`[${new Date()}] ${msg}`)
    };
  }

  // 原来的通用方法
  updateRuntimeState(key, value) {
    this.runtimeState[key] = value;
    this.logger.info(`状态更新：${key}=${value}`);
  }
}

module.exports = AppCore;

主模块里创建实例并传递：

// main.js
const AppCore = require('./app-core');
const config = require('./config');
const appCore = new AppCore(config);

// 把appCore实例传给其他模块
const { syncData } = require('./data-sync');
syncData(appCore, syncSource);

其他模块里的使用：

// data-sync.js
function syncData(appCore, source) {
  appCore.logger.info(`开始从${source}同步数据`);
  // 同步逻辑...
  appCore.updateRuntimeState('lastSyncTime', new Date().toISOString());
}

module.exports = { syncData };

这种方式把状态和操作状态的逻辑绑定在一起，符合面向对象设计，代码结构更清晰，也方便后续扩展功能。

• 尽量避免可变的全局状态：如果某个状态只需要读取，就把它设为只读，减少意外修改的风险。
• 遵循单一职责原则：拆分模块时，每个模块只负责一件事，比如日志模块就只处理日志，配置模块只处理配置，后期维护会轻松很多。
• 注意竞态条件：如果多个模块会同时修改同一个状态，一定要加必要的同步逻辑，避免出现数据不一致的问题。

内容的提问来源于stack exchange，提问作者Jake Wilson