TRAE-AI编程
在 Node.js 里定义全局变量，最常见也最容易踩坑的做法是直接给 global 对象挂属性，或者用看起来像全局的变量却因为模块作用域而并非真正共享。正确做法是：真正需要跨模块共享的状态才放进 global，并且优先用模块导出代替隐式全局。下面讲清三个边界，避免把项目写成难以维护的全局泥潭。很多新手从前端脚本转到 Node.js，习惯把配置随手挂到全局，结果在测试里反复出现诡异的串扰。其实只要分清 global、模块导出和环境变量三者的职责，这类问题从一开始就避得开。本文基于 Node.js 18 LTS 及以上版本讲解。
先看结论
Node.js 定义全局变量有三条边界必须先看清：第一，global 上的属性对整个进程可见，滥用会造成命名冲突与测试污染；第二，每个文件都是独立模块作用域，顶层 var 并不会变成全局；第三，区分「全局变量」和「环境变量」，跨环境配置应当走 process.env 而非 global。多数场景下，用模块导出（module.exports）比挂 global 更安全、更易追踪。关于 JavaScript 运行时本身的更多细节，可以先从 JavaScript 教程 补一遍作用域基础。
适用边界：以下内容基于 Node.js 18 LTS 及以上，global 对象的行为在各版本保持一致；ECMAScript 模块（.mjs / type:module）下顶层变量同样是模块作用域，与 CommonJS 一致。版本差异方面，旧版 Node 的某些内置全局（如 Buffer）始终存在，不要因此误以为自己定义的变量也是全局。需要快速查语法可翻 JavaScript 速查。
一、边界一：global 是进程级单例，滥用会冲突
直接在 global 上挂属性是最直观的 Node.js 全局变量写法，但它对整个进程共享：
// 危险：任何模块都能读写，容易互相覆盖
global.appConfig = { env: 'dev' };
console.log(global.appConfig.env);
预期结果（未在本机执行）：任意文件里都能读到 global.appConfig。问题在性能与取舍上：这种隐式共享让依赖关系变得不可见，多个模块改同一个 global 属性时会互相踩踏，单元测试也难以隔离。失败处理：如果发现某次测试随机失败，优先怀疑 global 被上一条测试污染，在测试框架的 beforeEach 里重置相关属性。想直观验证模块作用域，可以用 在线运行 JS 分别跑两个示例文件观察结果。
二、边界二：模块顶层变量不是全局
很多初学者以为在文件顶层写 var token = 'xxx' 之后别的文件就能直接用，这是最常见的误解。Node.js 中每个文件都是独立模块作用域，顶层声明只在当前模块内有效。
// a.js
const token = 'abc';
module.exports = token;
// b.js
const token = require('./a'); // 通过导出获取，而不是隐式全局
console.log(token);
对比来看，真正的全局应当放在 global，而模块间共享应当走 module.exports 显式导出。验证方式：在 b.js 里直接打印未导出的 token 会得到 undefined，这正是模块作用域在起作用，而不是 bug。模块导出才是 Node.js 推荐的共享方式，它让依赖关系显式化，也方便做树摇和测试替身。
三、边界三：环境变量不等于全局变量
配置信息（数据库地址、密钥、运行环境）应当用环境变量而非挂到 global。Node.js 通过 process.env 读取，天然按进程隔离、按部署环境区分。
// 通过环境变量读取配置，而不是 global.dbUrl
const dbUrl = process.env.DB_URL;
if (!dbUrl) {
throw new Error('缺少环境变量 DB_URL');
}适用边界：进程对象 process 本身是全局的，但 process.env 里的值来自启动时的环境，重启或换环境即变更，适合放敏感与可变配置。安全方面，切勿把密钥写死在代码或挂到可读的 global 上，应通过配置管理注入。混淆「全局变量」和「环境变量」是线上配置泄漏的高发原因，环境相关的东西一律走 process.env。
四、什么时候才真正需要 global
只有确实需要「整个进程唯一且被多方共享」的场景，才应该考虑 global，例如请求级别的缓存、单例连接池的引用。其余情况优先用模块导出，让依赖关系显式化，便于追踪与测试。
失败处理：一旦决定用 global，务必给它加命名前缀（如 global.__myapp_cache），降低与其他库的冲突概率，并在应用退出或测试清理时显式释放。更好的做法是用依赖注入，把共享状态作为参数传入，而不是依赖隐式全局。这样每条测试都能在干净状态下运行，避免互相污染。在 Node.js 实际项目里，最常见的全局变量误用是把用户会话、限流计数这类「看起来全局」的状态直接挂到 global，结果在并发请求里互相串号。正确做法是把这类状态放进请求作用域或连接池，仅把真正进程级的单例留在 global。定义全局变量前先问一句：这个状态是不是所有请求都必须共享？如果不是，就让它留在模块内，靠 module.exports 显式传递。
一个可运行的对比示例
在定义 Node.js 全局变量前，先用下面这个对比把三种共享方式理清：
// global：进程级，任何文件都能读到
global.counter = 0;
// 模块导出：只在本模块或被 require 的地方可见
module.exports = { counter: 0 };
// 环境变量：来自启动环境，重启即变
const env = process.env.NODE_ENV;
运行后会发现，直接改 global.counter 会在所有模块间互相影响，而 module.exports 的 counter 是各自实例。配置类的东西走 process.env，则能在一套代码里同时适配开发、测试、生产。理清这三者的边界，Node.js 的全局变量就不再是一个模糊的雷区，而是可以按场景安心选择的工具。
常见问题
Q：什么时候才适合用 global？
只在确实需要「整个进程唯一且被多方共享」的场景，例如请求级别的缓存、单例连接池的引用。其它共享需求都交给模块导出或依赖注入，让调用关系清晰、便于测试。
Q：模块里用 let / const 顶层声明，别的文件能拿到吗？
不能。Node.js 的模块作用域保证每个文件相互独立，顶层 let / const 只在当前文件可见，跨文件必须靠 module.exports 导出、require 引入。
Q：测试之间 global 互相污染怎么解决？
在测试框架的生命周期钩子里重置相关 global 属性，或者改用依赖注入，把共享状态作为参数传入，而不是依赖隐式全局。这样每条测试都能在干净状态下运行。
总结
Node.js 定义全局变量的关键是分清三件事：global 是进程级单例要慎用、模块顶层变量并非全局要用导出共享、环境变量走 process.env 而非 global。守住这三个边界，项目的可维护性和测试稳定性都会明显提升。把 global 当成最后手段，而不是默认仓库，是写出健壮 Node.js 服务的第一步。
