UUID v9（及 v7+）移除了默认导出，改为命名导出，导致传统 sinon.stub(uuid, 'v4') 失效；本文详解如何通过解构导入 + sinon.stub().value() 方式可靠 Stub v4，并强调清理机制与常见陷阱。
uuid v9（及 v7+）移除了默认导出，改为命名导出，导致传统 `sinon.stub(uuid, 'v4')` 失效；本文详解如何通过解构导入 + `sinon.stub().value()` 方式可靠 stub `v4`，并强调清理机制与常见陷阱。
随着 uuid 包自 v7 起全面转向 ECMAScript 模块（ESM）设计，其 CommonJS 兼容方式也同步更新：不再支持 require('uuid').v4 这样的属性访问，而是强制使用解构语法（如 const { v4 } = require('uuid')）获取函数。这意味着 uuid 对象本身已不再是可枚举的“模块对象”，而是一个仅提供命名导出的静态绑定——v4 在运行时是只读的、不可配置的函数引用，直接对 uuid.v4 执行 sinon.stub(uuid, 'v4') 会抛出 TypeError: Cannot stub non-existent own property v4。
✅ 正确做法是：先解构出 v4 函数，再对其本身进行值级 Stub。Sinon 的 .value() 方法允许我们用一个固定返回值完全替代目标函数的执行逻辑，适用于这种“常量式导出”的场景：
const sinon = require('sinon');
const { v4: uuidv4 } = require('uuid'); // ✅ 解构获取函数引用
let uuidV4Stub;
before(async () => {
// ✅ 对函数引用本身 stub，并指定返回值
uuidV4Stub = sinon.stub().value(() => 'TEST_UUID_1234567890');
// ⚠️ 关键：需将 stub 赋值给原变量作用域（如模块级或测试上下文）
// 若在严格模块化环境（如 ESM 测试），推荐使用代理/重绑定方案（见下文进阶说明）
});
after(() => {
// ✅ 必须显式 restore，避免污染后续测试
if (uuidV4Stub && typeof uuidV4Stub.restore === 'function') {
uuidV4Stub.restore();
}
});⚠️ 注意事项：
- 不能直接 sinon.stub(uuidv4)：uuidv4 是函数，不是对象属性，sinon.stub(fn) 仅用于包装方法调用，不改变原始引用；必须结合变量重绑定才能生效。
-
CommonJS 环境下的变量劫持技巧：由于 Node.js CommonJS 中 require 结果被缓存，且 uuidv4 是 const 绑定，上述代码中的 uuidv4 变量本身不可重赋值。因此，实际生效依赖于你如何在业务代码中使用该变量。推荐两种稳健方案：
- 业务层封装：在应用代码中定义 const generateId = () => uuid.v4()，然后 stub generateId；
- 模块级重绑定（推荐）：使用 proxyquire（Node.js）或 testdouble 替代 require，或在测试入口处通过 Object.defineProperty 劫持 uuid 模块的 v4 属性（需配合 sinon.replace()）。
? 进阶示例（使用 sinon.replace() 安全劫持模块导出）：
const sinon = require('sinon');
const uuid = require('uuid');
before(async () => {
// 替换 uuid 模块的 v4 导出为可控函数
sinon.replace(uuid, 'v4', sinon.fake.returns('MOCKED_V4_UUID'));
});
after(() => {
sinon.restore(); // 自动恢复所有替换，更安全
});? 总结：UUID v7+ 的模块化升级不是“breaking change”，而是“范式升级”。Stub 的核心思路应从“stub 对象属性”转向“stub 导出绑定”或“封装调用入口”。坚持解构导入、使用 .value() 或 .replace() 配合显式清理，即可无缝迁移至 uuid@9 并保障测试稳定性。
