JavaScript 单例模式实战：全局状态管理与工具类封装案例

作者：异步漫步

时间：2026-11-04

深入讲解 JavaScript 单例模式的核心原理与工程实战，通过对比 Class 惰性单例与 ES Module 机制，提供可落地的全局状态管理与存储工具类封装完整案例及避坑指南。

文章目录

一、单例模式的本质要求与判定机制

在 JavaScript 开发中，当多个业务模块需要协同操作同一份数据或同一套设备接口（例如用户登录凭证、页面主题、全局埋点客户端、音频上下文）时，如果不加约束地在各个页面中执行 new Manager()，就会在内存中创建出多个互不相通的对象副本。这种副本会导致数据不同步、事件监听重复触发以及内存泄漏。

单例模式（Singleton Pattern）从构造逻辑层面彻底切断了多次实例化的可能性。其核心原则包括两点：一是将实际的实例化过程封闭在受控的通道内，二是将首次生成的实例引用缓存起来，供后续所有调用方复用。

在现代 ECMAScript 语法中，利用 ES2022 的私有静态字段（Private Static Field）#instance 和公共静态方法 getInstance()，能够以语义明确的方式实现单例拦截。调用方不直接与构造器打交道，而是统一通过静态入口申请对象。

JavaScript 单例模式实战：全局状态管理与工具类封装案例 — 图 1：单例模式 getInstance() 执行与拦截判定时序推导

以下是一个具备防越权保护的最小化基础实现模板。当调用方试图绕过静态方法直接使用 new 操作符创建多份对象时，构造器会主动介入拦截：

BasicSingleton.jsECMAScript 2022

class ConfigCenter {
  // 静态私有字段：用于持有全局唯一实例的引用
  static #instance = null;

  constructor(initialOptions = {}) {
    // 拦截防护：若静态缓存已存在，直接抛出异常或返回已有实例
    if (ConfigCenter.#instance) {
      throw new Error("检测到违规实例化：请使用 ConfigCenter.getInstance() 获取全局唯一实例");
    }

    // 初始化实例属性
    this.env = initialOptions.env || "production";
    this.version = "1.0.0";
    this.createdAt = Date.now();

    // 锁定当前实例到静态缓存中
    ConfigCenter.#instance = this;
  }

  // 统一的外部静态访问入口
  static getInstance(options) {
    if (!ConfigCenter.#instance) {
      ConfigCenter.#instance = new ConfigCenter(options);
    }
    return ConfigCenter.#instance;
  }

  get(key) {
    return this[key];
  }
}

验证两处调用是否真正指向同一个对象，可以通过严格全等操作符（===）比对引用地址：

执行输出验证（示例）

const clientA = ConfigCenter.getInstance({ env: "staging" });

const clientB = ConfigCenter.getInstance();

console.log(clientA === clientB); // 输出: true

console.log(clientB.env); // 输出: "staging" (依然保持首次初始化的配置)

new ConfigCenter(); // 抛出 Error: 检测到违规实例化...

二、关键机制对比：Class 惰性单例与 ES Module 模块单例

在现代前端构建体系（Vite、Webpack、Rollup）普及后，很多开发者习惯在文件中直接执行实例化并通过 export const instance = new Service() 导出，借由 ES Module 规范中“模块只求值一次”的特性达成单例效果。然而，在同一业务开发约束下，Class 惰性单例与 ES 模块导出单例在机制运作上存在决定性的差异。

理解这两种方式的内在差异，对于大型系统的架构选型至关重要：

1. 实例化时机与首屏加载损耗

ES Module 模块单例是“饥饿式”（Eager）的。只要工程中某个文件通过 import { service } from './service' 引用了该模块，该文件在被 JS 引擎解析求值的阶段就会立即执行 new Service()。如果该服务的构造器中包含繁重的计算、大容量字典解析或环境探测，无论当前用户路径是否真正进入该功能页面，这笔耗时都会发生，甚至可能拉长核心主包的加载和首屏可交互时间（TTI）。

相对而言，Class 惰性单例（Lazy）只有在代码真正走到业务执行点、首次调用 Service.getInstance() 时才会分配堆内存并执行构造逻辑。若用户在本次访问中未触碰该功能，单例对象始终不会被创建，实现了真正的按需分配。

2. 动态参数注入能力

在复杂的工程环境中，部分单例在初始化时需要依赖异步请求结果或运行时上下文（例如：网关从接口获取的组织机构 ID、客户端动态下发的灰度标记）。ES Module 静态导出在模块定义时就已经固定，无法在外部 import 时传入动态构造入参；若要传参，往往不得不退化为“先导入一个空实例，再手动调用一次 instance.init(token)”，这打破了构造完整性保证。而 Class 惰性单例允许在首次调用时通过 Service.getInstance(runtimeOptions) 直接透传初始参数，保障对象在诞生之初就是合法且完整的。

3. 单元测试状态隔离与重置成本

在自动化测试（Jest、Vitest）场景下，测试用例应当保持严格正交互不干扰。ES Module 模块的导出对象会被模块加载器持久缓存在内存中。如果 Case 1 修改了单例内部的属性，Case 2 导入的依然是这个已被污染的脏对象，排查成本极高；强制清理通常需要调用昂贵且破坏性的 jest.resetModules() 重新加载全部依赖树。

Class 单例则可以在类上显式封装一个专供测试环境使用的 resetInstance() 静态方法，在每个用例执行完毕后将私有引用置空，轻盈地恢复原始隔离状态。

三、实战案例一：轻量级全局状态管理器（GlobalStateManager）

很多中小型项目或独立组件库不需要引入 Redux、Pinia 这样体积较大的状态库，但依然面临跨组件共享用户身份、系统主题、购物车数量等状态的需求。使用单例模式可以构建一个自包含的、具备单向数据流与发布-订阅机制的全局状态中枢。

为防止业务代码在组件内部以命令式方式随意篡改状态导致排查困难，状态管理器采用“私有状态 + Action 规约派发 + 深拷贝/冻结只读快照”的防护设计：

GlobalStateManager.js完整实战代码

class GlobalStateManager {
  static #instance = null;

  // 私有实例字段
  #state = {};
  #listeners = new Set();

  constructor(initialState = {}) {
    if (GlobalStateManager.#instance) {
      return GlobalStateManager.#instance;
    }

    // 初始化只读状态源
    this.#state = {
      user: null,
      theme: "light",
      notifications: [],
      ...initialState
    };

    GlobalStateManager.#instance = this;
  }

  // 全局唯一访问点
  static getInstance(initialState) {
    if (!GlobalStateManager.#instance) {
      GlobalStateManager.#instance = new GlobalStateManager(initialState);
    }
    return GlobalStateManager.#instance;
  }

  // 获取当前状态的浅冻结快照，杜绝外部直接修改引用
  getState() {
    return Object.freeze({ ...this.#state });
  }

  // 注册状态变更监听器，返回对应的注销函数
  subscribe(listener) {
    if (typeof listener !== "function") {
      throw new TypeError("订阅回调必须是函数类型");
    }
    this.#listeners.add(listener);

    // 返回解除订阅的闭包，便于组件卸载时调用
    return () => {
      this.#listeners.delete(listener);
    };
  }

  // 统一派发入口：通过预定义 action 变更状态
  dispatch(action) {
    if (!action || typeof action.type !== "string") {
      throw new Error("Action 必须包含有效的 type 字符串属性");
    }

    const previousState = this.getState();
    const nextState = this.#reducer(this.#state, action);

    // 状态更新与浅比较优化
    this.#state = nextState;

    // 广播通知全部活跃订阅者
    this.#notify(this.getState(), previousState, action);
  }

  // 内部纯函数 Reducer
  #reducer(state, action) {
    switch (action.type) {
      case "SET_USER":
        return { ...state, user: action.payload };
      case "CLEAR_USER":
        return { ...state, user: null };
      case "TOGGLE_THEME":
        return { ...state, theme: state.theme === "light" ? "dark" : "light" };
      case "ADD_NOTIFICATION":
        return {
          ...state,
          notifications: [...state.notifications, action.payload]
        };
      default:
        console.warn(`未知的 Action 类型: ${action.type}`);
        return state;
    }
  }

  // 广播更新
  #notify(currentState, prevState, action) {
    for (const listener of this.#listeners) {
      try {
        listener(currentState, prevState, action);
      } catch (err) {
        console.error("状态订阅回调执行异常:", err);
      }
    }
  }

  // 专供自动化测试套件的重置方法
  static resetForTesting() {
    if (GlobalStateManager.#instance) {
      GlobalStateManager.#instance.#listeners.clear();
      GlobalStateManager.#instance = null;
    }
  }
}

实战运行与多模块协同演示

在真实的单页应用中，用户在导航栏组件（NavBar）登录后，不仅需要更新个人中心，还需要通知底栏的主题设置组件。以下演示多模块调用同一单例实例的过程：

AppUsageDemo.js调用示例

// 模块 A：NavBar.js（获取单例并注册订阅）
const stateManagerA = GlobalStateManager.getInstance();
const unsubscribeNavBar = stateManagerA.subscribe((currentState, prevState, action) => {
  console.log(`[NavBar收到广播] 触发动作: ${action.type}`);
  if (action.type === "SET_USER") {
    console.log(`[NavBar渲染] 欢迎用户: ${currentState.user.name}`);
  }
});

// 模块 B：UserLoginModal.js（独立获取单例并派发事件）
const stateManagerB = GlobalStateManager.getInstance();
console.log("多处获取严格等价:", stateManagerA === stateManagerB); // true

// 触发用户登录成功
stateManagerB.dispatch({
  type: "SET_USER",
  payload: { id: 1001, name: "张小工", role: "Developer" }
});

// 切换全局主题
stateManagerB.dispatch({ type: "TOGGLE_THEME" });

// 验证不可变状态保护
const currentSnapshot = stateManagerA.getState();
try {
  currentSnapshot.theme = "custom-pink"; // 触发报错或静默忽略
} catch (e) {
  console.log("外部试图直接篡改状态被成功拦截");
}

执行控制台输出

多处获取严格等价: true

[NavBar收到广播] 触发动作: SET_USER

[NavBar渲染] 欢迎用户: 张小工

[NavBar收到广播] 触发动作: TOGGLE_THEME

TypeError: Cannot assign to read only property 'theme' of object '#<Object>'

四、实战案例二：通用存储工具类封装（StorageService）

在浏览器端操作 localStorage 或 sessionStorage 时，原生 API 仅支持存储纯字符串，且缺乏命名空间隔离、数据过期失效（TTL）以及防异常崩溃机制。如果各个业务模块零散地调用原生 API，极易造成键名覆盖冲突与过期数据堆积。

将本地存储能力封装为一个单例工具类，可以在全局统一持有命名空间前缀、加解密逻辑以及版本号，确保整个应用以一致的标准读写本地缓存。

StorageService.js带过期清理的单例存储工具类

class StorageService {
  static #instance = null;

  constructor(options = {}) {
    if (StorageService.#instance) {
      return StorageService.#instance;
    }

    this.prefix = options.prefix || "APP_V1_";
    this.driver = options.driver || window.localStorage;

    // 内存降级字典：在隐私模式或 Storage 被禁用时提供兜底支持
    this.memoryFallback = new Map();
    this.isStorageAvailable = this.#checkStorageAvailability();

    StorageService.#instance = this;
  }

  static getInstance(options) {
    if (!StorageService.#instance) {
      StorageService.#instance = new StorageService(options);
    }
    return StorageService.#instance;
  }

  // 探测 Storage 是否可用（解决 iOS 无痕浏览禁用 LocalStorage 的崩溃问题）
  #checkStorageAvailability() {
    try {
      const testKey = `__test_${Date.now()}__`;
      this.driver.setItem(testKey, "1");
      this.driver.removeItem(testKey);
      return true;
    } catch (e) {
      console.warn("客户端存储不可用，已自动降级为内存会话模式");
      return false;
    }
  }

  #formatKey(key) {
    return `${this.prefix}${key}`;
  }

  /**
   * 写入键值，支持指定存活时间（单位：毫秒）
   * @param {string} key 存储键名
   * @param {any} value 存储对象（自动 JSON 序列化）
   * @param {number|null} expireMs 过期时限，为 null 表示永久有效
   */
  set(key, value, expireMs = null) {
    const payload = {
      data: value,
      timestamp: Date.now(),
      expire: expireMs ? Date.now() + expireMs : null
    };

    const finalKey = this.#formatKey(key);
    const serialized = JSON.stringify(payload);

    if (this.isStorageAvailable) {
      try {
        this.driver.setItem(finalKey, serialized);
      } catch (err) {
        console.error("Storage 配额已超限或写入失败:", err);
      }
    } else {
      this.memoryFallback.set(finalKey, serialized);
    }
  }

  /**
   * 读取键值，若已过期则自动清除并返回默认值
   */
  get(key, defaultValue = null) {
    const finalKey = this.#formatKey(key);
    let serialized = null;

    if (this.isStorageAvailable) {
      serialized = this.driver.getItem(finalKey);
    } else {
      serialized = this.memoryFallback.get(finalKey) || null;
    }

    if (!serialized) {
      return defaultValue;
    }

    try {
      const payload = JSON.parse(serialized);

      // 过期判定
      if (payload.expire && Date.now() > payload.expire) {
        this.remove(key);
        return defaultValue;
      }

      return payload.data;
    } catch (e) {
      console.error(`解析键 [${finalKey}] 失败，返回默认值:`, e);
      return defaultValue;
    }
  }

  remove(key) {
    const finalKey = this.#formatKey(key);
    if (this.isStorageAvailable) {
      this.driver.removeItem(finalKey);
    } else {
      this.memoryFallback.delete(finalKey);
    }
  }

  // 批量清除仅属于当前命名空间下的所有数据，不影响页面其他程序写入的数据
  clearCurrentNamespace() {
    if (!this.isStorageAvailable) {
      this.memoryFallback.clear();
      return;
    }

    const keysToRemove = [];
    for (let i = 0; i < this.driver.length; i++) {
      const k = this.driver.key(i);
      if (k && k.startsWith(this.prefix)) {
        keysToRemove.push(k);
      }
    }

    for (const k of keysToRemove) {
      this.driver.removeItem(k);
    }
  }
}

StorageUsage.js调用与过期自动剔除验证

// 获取单例，指定全局命名空间前缀
const storage = StorageService.getInstance({ prefix: "SHOP_STORE_" });

// 写入有效时间为 2 秒的临时认证令牌
storage.set("authToken", "secret_token_12345", 2000);
console.log("写入即时读取:", storage.get("authToken")); // "secret_token_12345"

// 模拟延时 2.5 秒后读取
setTimeout(() => {
  const expiredValue = storage.get("authToken", "EXPIRED_FALLBACK");
  console.log("超时后读取:", expiredValue); // 输出: "EXPIRED_FALLBACK"
  console.log("底层键已被剔除:", localStorage.getItem("SHOP_STORE_authToken")); // null
}, 2500);

五、工程边界与避坑指南

单例模式虽然结构精简、调用便利，但若使用不当，极易引入隐蔽且难以定位的线上故障。在实际工程落地时，必须重点关注以下两个关键陷阱。

1. 自动化单元测试中的“跨用例状态污染”

由于单例实例的生命周期与整个应用程序（或测试进程）相同，一旦某个测试用例修改了单例内部的私有数据，接下来的所有用例都会受到残留数据的干扰。这会导致单测出现“单独运行全部通过，批量执行却随机报错”的诡异现象。

工程规范解法：必须在单例类中暴露专供测试清理的静态重置入口（如前文代码中的 resetForTesting()），并在测试测试框架的钩子函数中执行强制重置：

GlobalStateManager.test.jsJest / Vitest 隔离实践

describe("GlobalStateManager 状态隔离测试", () => {
  beforeEach(() => {
    // 每个用例执行前，彻底销毁上一个用例残留的单例对象
    GlobalStateManager.resetForTesting();
  });

  afterEach(() => {
    // 用例执行完毕后再次清空，防止遗留
    GlobalStateManager.resetForTesting();
  });

  test("用例 1：初始登录状态更新", () => {
    const manager = GlobalStateManager.getInstance();
    manager.dispatch({ type: "SET_USER", payload: { name: "李工" } });
    expect(manager.getState().user.name).toBe("李工");
  });

  test("用例 2：验证新用例状态纯净性", () => {
    const manager = GlobalStateManager.getInstance();
    // 由于执行了重置，这里的 user 必须是原始的 null，而不是上一个用例的 "李工"
    expect(manager.getState().user).toBeNull();
  });
});