ES2025 正式引入了 Iterator Helpers —— 一组挂载在 Iterator.prototype 上的函数式方法。本文从 API 用法、性能优势、规范算法三个层面逐层展开，带你真正理解这套机制的设计哲学与底层实现。

一个 Java 选手的十年之痒

故事得从 2014 年说起。

那一年，Java 8 发布了 Stream API，Java 开发者们几乎一夜之间拥有了这样的写法：

// Java 8 Stream API (2014)
List<String> result = employees.stream()
    .filter(e -> e.getSalary() > 50000)
    .map(Employee::getName)
    .sorted()
    .collect(Collectors.toList());

惰性求值、链式调用、函数式管线 —— 一切都那么自然。作为一个同时写 Java 和 JavaScript 的人，每次从 Java 切回 JS，心里都有一种说不出的落差。

同样的逻辑，在当时的 JavaScript 里只能这样写：

// JavaScript (2014)：只有 Array 有函数式方法
const result = employees
  .filter(e => e.salary > 50000)  // ← 只有数组才能这样
  .map(e => e.name)
  .sort();

看起来差不多？但仔细想想就会发现问题 —— 只有 Array 才有这套方法。

// 想对 Map 做管线操作？对不起，先转数组
const map = new Map([['a', 1], ['b', 2], ['c', 3]]);
[...map.keys()].filter(k => k !== 'b')

// 想处理 Generator 的无限序列？Java 可以，JS 不行
// Java: Stream.iterate(1, n -> n + 1).filter(...).limit(5)
// JS: ??? 没有原生支持

Java 的 Stream 可以来自任何数据源 —— Collection、Arrays、Files.lines()、IntStream.range()、甚至无限流 Stream.generate()。而 JavaScript 的函数式管线被绑死在 Array.prototype 上，其他可迭代对象（Map、Set、NodeList、Generator）全部被排除在外。

社区的尝试与局限

十年间，JavaScript 社区不断尝试填补这个空缺。Lodash、IxJS、wu.js、RxJS 等库都提供了类似的链式 API，但它们都有共同的限制：

核心问题：这些库都是外挂方案，而 Java 的 Stream API 是语言标准的一部分。任何实现 Collection 接口的对象都自动拥有 .stream()，不需要包装。

终于，原生支持来了

ES2025，等了十年之后，JavaScript 终于在语言层面给出了答案：Iterator Helpers。

// ES2025 —— 原生 Iterator Helpers
// 不需要任何库，不需要包装，所有迭代器直接可用
new Map([['a', 1], ['b', 2], ['c', 3]])
  .keys()
  .filter(k => k !== 'b')
  .toArray();
// → ['a', 'c']

function* naturals() {
  let n = 1;
  while (true) yield n++;
}

naturals()
  .filter(n => n % 2 === 0)
  .map(n => n * 10)
  .take(5)
  .toArray();
// → [20, 40, 60, 80, 100]

没有包装器，没有 pipe，没有 .value() 解包。 所有实现 Iterator 协议的对象（数组迭代器、Map 迭代器、Set 迭代器、Generator、DOM 的 NodeList 等）都直接拥有这些方法。

JavaScript 终于在 2025 年拥有了与 Java Stream API 相当的原生能力。

三个核心痛点

在 Iterator Helpers 出现之前，JavaScript 处理迭代数据有三个绕不过去的问题：

1. 内存浪费 — 中间数组开销巨大

// ❌ 每一步都创建完整的临时数组
hugeArray.filter(x => x > 10).map(x => x * 2);

// ✅ 逐元素流式处理，零中间分配
hugeArray.values().filter(x => x > 10).map(x => x * 2).toArray();

2. 无法处理无限序列

// ❌ 展开无限生成器 → 程序卡死
[...naturals()].filter(n => n % 2 === 0).slice(0, 5);

// ✅ 按需拉取，只处理必要的元素
naturals().filter(n => n % 2 === 0).take(5).toArray();

3. 语义割裂 — 只有数组能用函数式方法

// ❌ Map/Set/Generator 必须先转数组
[...map.keys()].filter(k => k !== 'b');

// ✅ 所有迭代器统一支持
map.keys().filter(k => k !== 'b').toArray();

Iterator Helpers 的解决方案：惰性求值避免中间数组，按需拉取支持无限序列，统一挂载在 Iterator.prototype 上让所有迭代器都能用。

Iterator Helpers 全家福

ES2025 标准定义了以下方法，分为两类：

惰性方法（返回新的 Iterator Helper）

这五个方法不会立即消费迭代器，而是返回一个新的惰性迭代器，只在你调用 .next() 时才逐个处理元素：

急切方法（立即消费迭代器，返回结果值）

静态方法

实战：Iterator Helpers 解决了哪些真实痛点

无限序列的优雅处理

// 生成器：无限的自然数序列
function* naturals() {
  let n = 1;
  while (true) yield n++;
}

// 找出前 5 个能被 7 整除的平方数
const result = naturals()
  .map(n => n * n)
  .filter(n => n % 7 === 0)
  .take(5)
  .toArray();

console.log(result);
// → [49, 196, 441, 784, 1225]

这段代码不会死循环，因为每个方法都是惰性的：.take(5) 只会向上游拉取恰好够用的元素，收集到 5 个结果后整条管线自动停止。

传统的数组方法无法处理无限序列：[...naturals()] 会导致内存溢出。

DOM 操作的函数式改写

// 获取页面中所有标题包含 "API" 的文章链接
const apiLinks = document.querySelectorAll('article h2')
  .values()                                    // → Iterator
  .filter(el => el.textContent.includes('API'))
  .map(el => el.closest('article').querySelector('a').href)
  .toArray();

不再需要 [...nodeList].filter(...) 这种先展开再操作的写法。

Map / Set 的直接链式操作

const scores = new Map([
  ['Alice', 92],
  ['Bob', 67],
  ['Carol', 85],
  ['Dave', 45],
]);

// 找出所有及格的学生名字
const passed = scores.entries()
  .filter(([_, score]) => score >= 60)
  .map(([name, _]) => name)
  .toArray();

// → ['Alice', 'Bob', 'Carol']

与 flatMap 的组合：扁平化嵌套结构

const departments = new Map([
  ['Engineering', ['Alice', 'Bob']],
  ['Design', ['Carol']],
  ['Product', ['Dave', 'Eve']],
]);

// 将所有部门的员工扁平化为一个序列
const allEmployees = departments.values()
  .flatMap(members => members)  // 数组是可迭代对象，flatMap 会迭代其元素
  .toArray();

// → ['Alice', 'Bob', 'Carol', 'Dave', 'Eve']

注意：与 Array.prototype.flatMap() 不同，Iterator 的 flatMap 的回调必须返回一个迭代器或可迭代对象，不能返回普通值。

Iterator.from：统一异构迭代器

// 一个"不合格"的迭代器 —— 有 next() 但没有继承 Iterator.prototype
const rawIterator = {
  current: 0,
  next() {
    return this.current < 3
      ? { value: this.current++, done: false }
      : { done: true };
  }
};

// 直接调用 .map() 会报错：rawIterator.map is not a function
// 用 Iterator.from() 包装后就可以了：
Iterator.from(rawIterator)
  .map(n => n * 100)
  .toArray();
// → [0, 100, 200]

处理分页 API 数据

// 懒加载分页数据的生成器
function* fetchAllPages(apiUrl, maxPages = 10) {
  let page = 1;
  // 注意：实际项目中这里应该用 async/await，但需要配合 Async Iterator Helpers（仍在提案中）
  // 这里简化为同步示例
  while (page <= maxPages) {
    const users = mockFetchPage(apiUrl, page);  // 模拟同步获取
    if (users.length === 0) break;

    for (const item of users) {
      yield item;
    }
    page++;
  }
}

// 获取前 20 个活跃用户（评分 > 4.5）
const topUsers = Iterator.from(fetchAllPages('/api/users'))
  .filter(user => user.rating > 4.5)
  .take(20)
  .toArray();

// 只会遍历必要的页数，而不是拉取全部数据

文件流处理

// 从内存中的日志数组提取 404 错误的 URL
const logLines = [
  '2024-01-01 GET /home HTTP/1.1 200',
  '2024-01-01 GET /missing HTTP/1.1 404',
  '2024-01-01 POST /api HTTP/1.1 200',
  '2024-01-01 GET /notfound HTTP/1.1 404',
  // ... 更多日志
];

const notFoundUrls = logLines.values()
  .filter(line => line.includes('404'))
  .map(line => {
    const match = line.match(/GET\s+(\S+)\s+HTTP/);
    return match ? match[1] : null;
  })
  .filter(url => url !== null)
  .take(100)  // 只取前 100 个
  .toArray();

// → ['/missing', '/notfound']

组合多个数据源

// 合并多个配置源，后面的覆盖前面的
function* mergeConfigs(...sources) {
  const seen = new Set();

  // 从后往前遍历（后面的优先级高）
  for (const source of sources.reverse()) {
    for (const [key, value] of source.entries()) {
      if (!seen.has(key)) {
        seen.add(key);
        yield [key, value];
      }
    }
  }
}

const defaults = new Map([['theme', 'light'], ['lang', 'en']]);
const userPrefs = new Map([['theme', 'dark']]);
const urlParams = new Map([['lang', 'zh']]);

const finalConfig = new Map(
  Iterator.from(mergeConfigs(defaults, userPrefs, urlParams))
    .toArray()
);
// → Map { 'lang' => 'zh', 'theme' => 'dark' }

数据管道：CSV 解析与转换

// 解析 CSV 行的生成器
function* parseCSV(text) {
  for (const line of text.split('\n')) {
    if (line.trim()) {
      yield line.split(',').map(cell => cell.trim());
    }
  }
}

const csvData = `
name,age,city
Alice,30,NYC
Bob,25,LA
Carol,35,SF
Dave,28,NYC
`;

// 提取所有 NYC 居民的姓名和年龄
const nycResidents = Iterator.from(parseCSV(csvData))
  .drop(1)  // 跳过表头
  .filter(([name, age, city]) => city === 'NYC')
  .map(([name, age]) => ({ name, age: parseInt(age) }))
  .toArray();
// → [{ name: 'Alice', age: 30 }, { name: 'Dave', age: 28 }]

性能优势：惰性求值 vs 急切求值

让我们用一个真实场景来对比。假设你有一个日志分析函数，需要从海量日志中找出前 5 条错误日志的摘要：

const logs = Array.from({ length: 1_000_000 }, (_, i) => ({
  level: i % 100 === 0 ? 'error' : 'info',
  message: `Log entry #${i}`,
  timestamp: Date.now() - i * 1000,
}));

// ❌ 传统方式：filter 必须扫完整个数组，无法提前退出
const oldWay = logs
  .filter(log => log.level === 'error')        // 必须遍历全部 1M 条，生成 10,000 条的中间数组
  .slice(0, 5)                                 // 取前 5 条
  .map(log => `[${log.level}] ${log.message}`); // 只 map 5 条，这步没问题
// 瓶颈在 filter：为了找 5 条 error，扫描了 100 万条日志，分配了 1 万条的中间数组

// 你可能会说：那我手写 for 循环提前退出
const loopWay = [];
for (const log of logs) {
  if (log.level === 'error') {
    loopWay.push(`[${log.level}] ${log.message}`);
    if (loopWay.length === 5) break;  // 找到第 5 条就停
  }
}
// 性能最优，但牺牲了可读性和可组合性

// ✅ Iterator Helpers：既有链式的可读性，又有 for 循环的性能
const newWay = logs.values()
  .filter(log => log.level === 'error')         // 惰性，不分配数组
  .map(log => `[${log.level}] ${log.message}`)   // 惰性，不分配数组
  .take(5)                                       // 只拉取 5 个就停止
  .toArray();

// 结果相同，但 newWay 只遍历了 ~401 个元素（到第 5 个 error 为止）
// oldWay 的 filter 必须扫完全部 1M 条，即使只需要前 5 个匹配

核心问题在于：Array 的 filter 没有"够了就停"的能力。它必须跑完整个数组才能返回结果，即使你后面紧跟 .slice(0, 5)。手写 for 循环可以提前退出，但代价是丢失链式调用的可读性和可组合性。

Iterator Helpers 让你不再需要做这个取舍 —— 链式写法 + 提前终止，两者兼得。

核心区别在于执行模型：

实际性能测试数据

下面是在 Node.js 22.0 / V8 12.4 环境下的实际基准测试结果（100万条数据，取前5条）：

// 测试代码
const logs = Array.from({ length: 1_000_000 }, (_, i) => ({
  level: i % 100 === 0 ? 'error' : 'info',
  message: `Log entry #${i}`,
}));

// 测试1: 传统 Array 方法
console.time('Array methods');
const result1 = logs
  .filter(log => log.level === 'error')
  .slice(0, 5)
  .map(log => `[${log.level}] ${log.message}`);
console.timeEnd('Array methods');

// 测试2: Iterator Helpers
console.time('Iterator Helpers');
const result2 = logs.values()
  .filter(log => log.level === 'error')
  .take(5)
  .map(log => `[${log.level}] ${log.message}`)
  .toArray();
console.timeEnd('Iterator Helpers');

// 测试3: 手写 for 循环
console.time('Manual loop');
const result3 = [];
for (const log of logs) {
  if (log.level === 'error') {
    result3.push(`[${log.level}] ${log.message}`);
    if (result3.length === 5) break;
  }
}
console.timeEnd('Manual loop');

测试结果：

结论：Iterator Helpers 的性能接近手写循环（仅慢 30%），但比传统 Array 方法快 50 倍以上，且没有中间内存分配。

底层原理：惰性求值是怎么实现的

前面我们看到了 Iterator Helpers 的强大功能。但它是如何做到惰性求值的？为什么链式调用不会立即执行？

答案在于 Generator 机制的复用。ECMAScript 规范将每个 Iterator Helper（map、filter 等）都实现为一个 Generator，利用 Generator 的暂停/恢复能力实现惰性执行。

规范如何表示迭代器

规范用内部记录（Iterator Record）来跟踪迭代器的状态，包括：

• 迭代器对象本身
• 缓存的 .next() 方法引用（性能优化：避免每次重复查找属性）
• 是否已完成的标记

惰性的秘密：类似 Generator 的暂停机制

当你调用 map(fn) 或 filter(fn) 时，并不会立即执行。规范将这些方法实现为 Generator 函数，利用 Generator 的暂停/恢复能力：

// 概念性的伪代码（简化版）
Iterator.prototype.map = function(mapper) {
  const source = this;
  return (function* () {  // ← 返回一个 Generator
    let counter = 0;
    while (true) {
      const { value, done } = source.next();
      if (done) return;
      yield mapper(value, counter++);  // ← 每次暂停在这里
    }
  })();
};

关键点：

• yield 让函数暂停，把处理后的值返回
• 下次调用 .next() 时，从 yield 的位置继续执行
• map 每个值都返回，filter 只在满足条件时才 yield

这就是为什么链式调用不会立即执行——每个方法都返回一个新的 Generator，只有在你调用 .toArray() 或手动 .next() 时才开始拉取数据。

take 的特殊之处：主动关闭迭代器

take 的核心逻辑是计数器 + 提前终止：

闭包逻辑：
  令 remaining = limit
  循环：
    如果 remaining === 0：
      return IteratorClose(iterated)  // ← 主动关闭上游
    remaining -= 1
    Yield(上游的值)

重要细节：当 remaining 减到 0 时，take 会调用 IteratorClose 主动关闭上游迭代器。这确保了资源（如文件句柄、数据库连接）能被正确释放。

工厂机制：CreateIteratorFromClosure

所有惰性方法最终都通过 CreateIteratorFromClosure 将闭包包装成迭代器。这个工厂函数本质上创建了一个 Generator 对象，拥有 [[GeneratorState]] 和 [[GeneratorContext]] 等内部插槽，用于支持暂停/恢复机制。

链式调用的执行流

理解了单个方法的工作原理后，我们来看链式调用时数据是如何流动的：

naturals()
  .filter(n => n % 2 === 0)
  .map(n => n * 10)
  .take(2)
  .toArray();

执行时的调用栈展开如下：

toArray()
  → 调用 take_helper.next()
    → take 闭包恢复执行
    → 调用 map_helper.next()
      → map 闭包恢复执行
      → 调用 filter_helper.next()
        → filter 闭包恢复执行
        → 调用 naturals_generator.next()  → 得到 1
        → predicate(1) = false → 不 yield, 继续循环
        → 调用 naturals_generator.next()  → 得到 2
        → predicate(2) = true → Yield(2), 挂起 filter
      ← 返回 { value: 2 }
      → mapper(2) = 20 → Yield(20), 挂起 map
    ← 返回 { value: 20 }
    → remaining: 2→1, Yield(20), 挂起 take
  ← 返回 { value: 20 }
  → 存入结果数组

  → 调用 take_helper.next()
    → ... 同样的过程 ...
    → naturals: 3 → filter 跳过 → naturals: 4 → filter 通过
    → map(4) = 40, take remaining: 1→0
  ← 返回 { value: 40 }
  → 存入结果数组

  → 调用 take_helper.next()
    → remaining === 0 → IteratorClose → 关闭整条管线
  ← 返回 { value: undefined, done: true }

结果: [20, 40]

这就是"拉模型"（Pull Model）：数据不是从源头推到末端，而是由末端（toArray）按需从上游逐个拉取。每个中间节点都是一个暂停点，不需要缓存任何中间结果。

与 Generator 的关系

Iterator Helper 在规范层面就是 Generator。那它和我们手写的 Generator 有什么区别？

Iterator Helper ≈ 受限的 Generator

// 手写 Generator 实现 map
function* manualMap(iterator, fn) {
  for (const value of iterator) {
    yield fn(value);
  }
}

// 等价于
iterator.map(fn);

但 Iterator Helper 有几个刻意的限制：

1. 不支持 .throw() — Helper 不暴露 throw 方法，你不能向管线中注入异常
2. 不转发 .next() 的参数 — helper.next(someValue) 中的 someValue 会被忽略
3. .return() 会关闭底层迭代器 — 调用 helper.return() 会沿着链条关闭所有上游迭代器

这些限制是故意的设计决策。规范的原话是：

The philosophy is that any iterators produced by the helpers only implement the iterator protocol and make no attempt to support generators which use the remainder of the generator protocol.

换句话说：Iterator Helper 虽然底层是 Generator 机制，但对外只暴露纯粹的 Iterator 接口。

继承链

Object.prototype
  └── Iterator.prototype          (定义了 map/filter/take 等方法)
       └── %IteratorHelperPrototype%  (定义了 next/return，以及 @@toStringTag = "Iterator Helper")
            └── 每个 helper 实例

所有 Iterator Helper 实例共享同一个原型 %IteratorHelperPrototype%，这个原型本身继承自 Iterator.prototype。因此 helper 的返回值本身也是迭代器，可以继续链式调用。

自己实现一个简化版 Iterator Helpers

理解了规范算法后，让我们用 JavaScript 实现一个简化版，体会底层机制：

注意：每个方法（map、filter 等）中的 counter 参数表示该操作接收到的元素索引，而非原始数据的位置。例如 [1,2,3,4,5].filter(n => n > 2).map((n, i) => ...) 中，map 的 i 从 0 开始计数（对应值 3, 4, 5），而不是从原数组的索引 2 开始。

class LazyIterator {
  #source;

  constructor(source) {
    // source 是一个 { next() } 对象
    this.#source = source;
  }

  next() {
    return this.#source.next();
  }

  [Symbol.iterator]() {
    return this;
  }

  return() {
    return this.#source.return?.() ?? { value: undefined, done: true };
  }

  // —— 惰性方法 ——

  map(mapper) {
    const source = this;
    let counter = 0;
    return new LazyIterator({
      next() {
        const { value, done } = source.next();
        if (done) return { value: undefined, done: true };
        return { value: mapper(value, counter++), done: false };
      },
      return() {
        return source.return?.() ?? { value: undefined, done: true };
      }
    });
  }

  filter(predicate) {
    const source = this;
    let counter = 0;
    return new LazyIterator({
      next() {
        while (true) {
          const { value, done } = source.next();
          if (done) return { value: undefined, done: true };
          if (predicate(value, counter++)) {
            return { value, done: false };
          }
          // 不满足条件，继续拉取下一个（这就是 filter 内部的循环）
        }
      },
      return() {
        return source.return?.() ?? { value: undefined, done: true };
      }
    });
  }

  take(limit) {
    if (limit <= 0) {
      return new LazyIterator({
        next() { return { value: undefined, done: true }; },
        return() { return { value: undefined, done: true }; }
      });
    }
    const source = this;
    let remaining = limit;
    let closed = false;
    return new LazyIterator({
      next() {
        if (!closed && remaining <= 0) {
          source.return?.();
          closed = true;  // 防止重复关闭
        }
        if (remaining <= 0) {
          return { value: undefined, done: true };
        }
        remaining--;
        return source.next();
      },
      return() {
        if (!closed) {
          closed = true;
          return source.return?.() ?? { value: undefined, done: true };
        }
        return { value: undefined, done: true };
      }
    });
  }

  // —— 急切方法 ——

  toArray() {
    const result = [];
    while (true) {
      const { value, done } = this.next();
      if (done) return result;
      result.push(value);
    }
  }

  // ... 其他方法（forEach、find、some、every、drop、flatMap 等）实现类似，此处省略

  // 静态工厂方法
  static from(iteratorOrIterable) {
    if (iteratorOrIterable == null) {
      throw new TypeError('Cannot convert null or undefined to iterator');
    }
    // 先检查是否已经是迭代器（有 .next() 方法）
    if (typeof iteratorOrIterable.next === 'function') {
      return new LazyIterator(iteratorOrIterable);
    }
    // 再检查是否是可迭代对象（有 Symbol.iterator）
    if (typeof iteratorOrIterable[Symbol.iterator] === 'function') {
      return new LazyIterator(iteratorOrIterable[Symbol.iterator]());
    }
    throw new TypeError('Argument must be an iterator or iterable object');
  }
}

验证

// 使用前面定义的 naturals() 生成器
const result = LazyIterator.from(naturals())
  .filter(n => n % 2 === 0)
  .map(n => n * 10)
  .take(5)
  .toArray();

console.log(result);
// → [20, 40, 60, 80, 100]

这个简化版省略了很多规范要求的错误处理（如 IfAbruptCloseIterator），但核心的惰性执行 + 拉模型 + 链式代理逻辑是一致的。

引擎优化

JavaScript 引擎（如 V8）对 Iterator Helpers 做了多项优化：

• 状态机代替协程：避免完整的协程切换开销
• 内联缓存：缓存 .next() 方法引用，避免重复属性查找
• 对象消除：通过逃逸分析优化掉临时的 { value, done } 对象

这些优化让 Iterator Helpers 的性能接近手写循环。

注意事项与最佳实践

迭代器是一次性的

const iter = [1, 2, 3].values().map(n => n * 2);

console.log(iter.toArray()); // → [2, 4, 6]
console.log(iter.toArray()); // → [] ← 已经消费完了！

回调中的异常会关闭迭代器

function* gen() {
  try {
    yield 1;
    yield 2;
    yield 3;
  } finally {
    console.log('generator cleaned up');
  }
}

gen()
  .map(n => {
    if (n === 2) throw new Error('boom');
    return n;
  })
  .toArray();

// 输出: "generator cleaned up"
// 抛出: Error: boom

规范中的 IfAbruptCloseIterator 确保了：当回调抛出异常时，底层迭代器的 .return() 会被自动调用，触发 finally 清理逻辑。

flatMap 只接受可迭代对象

// ❌ 错误：返回普通值
[1, 2, 3].values().flatMap(n => n * 2);
// TypeError: 回调返回的值不是可迭代对象

// ✅ 正确：返回可迭代对象
[1, 2, 3].values()
  .flatMap(n => [n, n * 2])
  .toArray();
// → [1, 2, 2, 4, 3, 6]

Iterator.from 的边界情况

// ❌ null 或 undefined 会抛出明确的错误
Iterator.from(null);
// TypeError: Cannot convert null or undefined to iterator

// ✅ 已经是迭代器的对象会直接返回包装
const iter = [1, 2, 3].values();
Iterator.from(iter);  // 可用

// ✅ 可迭代对象会调用其 Symbol.iterator
Iterator.from([1, 2, 3]);
Iterator.from(new Set([1, 2, 3]));
Iterator.from('abc');  // 字符串也是可迭代的

何时用 Iterator Helpers，何时用 Array 方法

浏览器兼容性

Iterator Helpers 已作为 ES2025 标准正式发布，截至 2026 年初已获得全面支持：

对于需要兼容旧环境的场景，可以使用 core-js 的 polyfill。

展望：Async Iterator Helpers

同步 Iterator Helpers 进入标准后，Async Iterator Helpers 提案（目前 Stage 2）正在推进。它的 API 与同步版本几乎一致：

// 未来的 Async Iterator Helpers（API 细节可能随提案演进而变化）
const response = await fetch('/api/stream');

await AsyncIterator.from(response.body)
  .filter(chunk => chunk.length > 0)
  .map(chunk => new TextDecoder().decode(chunk))
  .take(10)
  .forEach(text => console.log(text));

异步版本的独特之处在于并发支持的可能性 —— 比如 .map() 中的 fetch 调用可以并行执行，而不是严格串行。这是同步版本无法提供的能力。

总结

Iterator Helpers 的核心价值：

1. 惰性求值 — 按需处理，避免中间数组
2. 统一协议 — 所有迭代器都能用，无需包装
3. 原生支持 — 不需要任何库，开箱即用
4. 资源安全 — 自动管理迭代器生命周期

从 2014 年 Java 8 发布 Stream API 开始，JavaScript 开发者等待了十年。现在，我们终于有了原生的、高性能的函数式迭代器 API。

当你下次写 [...someIterator].filter(...).map(...) 时，去掉展开运算符，你不仅节省了几个字符，更避免了一整套中间数组的分配和遍历。

参考资料：

• TC39 Iterator Helpers 提案
• ECMAScript 2025 规范
• V8 Blog: Iterator Helpers
• MDN: Iterator
• Async Iterator Helpers 提案

目录

• 引言：为什么原型是前端工程师绕不过去的一课
• 一、先建立统一认知：对象原型到底是什么
• 二、prototype 和 [[Prototype]] 不是一回事
• 三、从 new 和内存视角理解实例、构造函数与原型
• 四、函数原型上的高频知识点：共享属性与 constructor
• 五、重写原型对象时，为什么最容易踩坑
• 六、创建对象的推荐姿势：实例数据放 this，共享方法放 prototype
• 实战建议
• 总结：关键结论与团队落地建议

引言：为什么原型是前端工程师绕不过去的一课

很多团队在日常开发里已经很少手写“构造函数 + 原型”这套模式了，更多时候我们写的是 class、对象字面量、组合式函数，甚至直接用框架帮我们屏蔽底层细节。于是原型这件事，常常只在面试里出现，看起来像“八股”，但一旦线上排查问题，它又会突然变得非常真实：

• 为什么两个实例的方法地址相同？
• 为什么给对象赋值后没有覆盖到原型上的值？
• 为什么重写 prototype 之后，constructor 看起来“不对了”？
• 为什么控制台里 __proto__ 看起来什么都有，但代码里又不建议用它？
• 为什么 class 最终仍然离不开原型链？

如果对这些问题没有统一心智模型，工程上就会出现两类常见问题：一类是“会用但讲不清”，另一类是“改得动但不敢改”。而原型真正的价值，不在于背定义，而在于帮助我们理解 JavaScript 的对象系统、继承机制、方法共享、内存结构，以及很多框架设计背后的语言基础。

这篇文章的目标很明确：不是把概念堆给你，而是把“对象、函数、构造函数、实例、原型、构造器”这几者之间的关系，一次性串起来。读完之后，你至少应该能建立起一个稳定的判断标准：什么应该挂在实例上，什么应该挂在原型上，什么时候可以重写原型，重写后又要补什么。

一、先建立统一认知：对象原型到底是什么

在 JavaScript 中，几乎每个对象都带着一个隐藏的内部链接，这个内部链接在规范里叫 [[Prototype]]。它会指向另一个对象，而这个“被指向的对象”，就是当前对象的原型对象。

你可以把它理解成：当前对象在找不到某个属性时，下一站该去哪里找。

1. 原型最核心的作用：兜底查找

当我们访问一个对象属性时，会触发内部的 [[Get]] 过程；当我们给对象设置属性时，会触发 [[Set]] 过程。

下面这个例子最能说明问题：

function A() {}
A.prototype.x = 10

const obj = new A()

console.log(obj.x) // 10，obj 自身没有 x，沿原型找到 A.prototype.x

obj.x = 20
console.log(obj.x) // 20，此时 obj 自身已经有了 x

这里发生了两件事：

1. 第一次读 obj.x，对象自身没有，沿着原型找到 A.prototype.x
2. 第二次写 obj.x = 20，是在实例自身新增了一个同名属性，而不是改掉原型上的 x

这也是很多人第一次理解“共享”和“遮蔽（shadowing）”的关键入口。

2. 对象字面量创建出来的对象，也有原型

很多人以为只有通过构造函数创建出来的对象才有原型，这其实不对。只要是普通对象，通常都有 [[Prototype]]。

const obj = { name: 'XiaoWu' }
const foo = {}

console.log(obj.__proto__)
console.log(foo.__proto__)

图：隐式原型在浏览器与终端中的表现

控制台里你看到的结果，和真实运行时的内部结构并不完全等价。浏览器控制台为了方便调试，会把一些继承来的内容也展开给你看；Node 的输出则更接近“对象本身 + 原型关系”的表现。

从理解层面，可以先把它抽象成下面这样：

const obj = { name: 'XiaoWu', __proto__: {} }
const foo = { __proto__: {} }

当然，真正的 [[Prototype]] 不是你字面量里真的写出来的这个字段，而是引擎内部维护的链接关系。

3. __proto__、[[Prototype]]、Object.getPrototypeOf 到底什么关系？

这是高频混淆点，必须一次说清：

• [[Prototype]]：规范层面的内部槽，真实存在，但你不能直接写代码访问这个名字
• __proto__：历史遗留的访问器属性，调试方便，但不推荐作为正式代码依赖
• Object.getPrototypeOf(obj)：标准 API，推荐在正式代码里使用

const obj = { name: '小吴' }

console.log(Object.getPrototypeOf(obj))

调试场景里，obj.__proto__ 确实更顺手；工程代码里，优先使用 Object.getPrototypeOf(obj)。原因很简单：

• 语义标准、跨环境更稳定
• 可维护性更高
• 降低“我在操作语言底层 hack 口子”的心智负担

顺手补一句：今天的引擎几乎都支持 __proto__，但“能用”不等于“应该作为主路径使用”。

本章小结

• 每个对象的核心原型关系，体现在内部的 [[Prototype]]
• 读取属性找不到时，会沿原型继续查找
• 给实例赋值，不等于改原型；很多时候只是“在实例自身新增同名属性”
• __proto__ 更适合调试，正式代码优先 Object.getPrototypeOf
• 理解原型，本质是在理解 JavaScript 如何做“属性查找”和“能力复用”

二、prototype 和 [[Prototype]] 不是一回事

聊原型最容易踩的第一个坑，就是把 prototype 和 [[Prototype]] 混为一谈。它们名字很像，但角色完全不同。

1. prototype 是函数身上的属性，不是所有对象都有

先看例子：

function foo() {}

const obj = {}

console.log(foo.prototype) // 普通函数默认有 prototype
console.log(obj.prototype) // undefined，普通对象没有 prototype

这里有一个非常重要的判断标准：

• prototype 是函数对象上的一个属性，主要给“作为构造函数使用”时服务
• [[Prototype]] 是对象内部的原型链接，普通对象、函数对象都可能有

也就是说：

• 函数是对象，所以函数也有 [[Prototype]]
• 但普通对象不是函数，所以普通对象没有 prototype

2. 这两个概念各自负责什么？

可以直接用一句最工程化的话来理解：

• prototype：定义将来由这个构造函数创建出来的实例，应该共享什么
• [[Prototype]]：当前这个对象，实际沿哪条链路去查找属性

它们的职责并不重复：

1. 归属不同
   prototype 属于函数；[[Prototype]] 属于对象

2. 作用不同
   prototype 用来定义共享能力；[[Prototype]] 用来参与查找路径

3. 时机不同
   prototype 通常在定义阶段配置；[[Prototype]] 通常在对象创建时被确定

3. 纠正一个特别容易出现的误区

很多人在刚学到这里时，会误以为：

“函数自己的隐式原型会指向它自己的显式原型”

这是错误的。

准确关系应该是：

• foo.prototype：给将来 new foo() 出来的实例用
• Object.getPrototypeOf(foo)：函数对象 foo 自己的原型，通常是 Function.prototype

也就是说：

function foo() {}

console.log(Object.getPrototypeOf(foo) === Function.prototype) // true

而实例和构造函数之间的正确关系，是下一节的重点：

const f1 = new foo()
console.log(Object.getPrototypeOf(f1) === foo.prototype) // true

4. new 到底做了什么？

理解原型，绕不开 new。把它拆开看，会清晰很多。

new Foo() 大致会做下面几步：

1. 创建一个全新的空对象
2. 把这个对象的 [[Prototype]] 指向 Foo.prototype
3. 用这个新对象作为 this 执行构造函数
4. 如果构造函数没有显式返回对象，就返回这个新对象

所以，实例为什么能访问构造函数原型上的方法？答案就在第 2 步。

function Foo() {}

const f1 = new Foo()
const f2 = new Foo()

console.log(Object.getPrototypeOf(f1) === Foo.prototype) // true
console.log(Object.getPrototypeOf(f2) === Foo.prototype) // true

这就是为什么不同实例可以“共享一套方法定义”，却又拥有各自不同的数据。

本章小结

• prototype 和 [[Prototype]] 名字相似，但职责完全不同
• 普通对象没有 prototype，函数通常有
• 实例的 [[Prototype]] 会在 new 时指向构造函数的 prototype
• 函数对象自己的原型通常是 Function.prototype，不是它自己的 prototype
• 只要把“定义共享能力”和“参与属性查找”分开理解，很多混乱都会消失

三、从 new 和内存视角理解实例、构造函数与原型

如果只停留在语法层，原型会越学越抽象。真正把它看懂，最有效的方式是换成“引用关系”和“内存指向”的视角。

1. Person、实例对象和原型对象之间是什么关系？

先看一个最简单的例子：

function Person() {}

console.log(Person.prototype)

很多人看到这里会困惑：Person 是函数，Person.prototype 是对象，那实例和它们之间是怎么连起来的？

关键结论只有一个：

同一个构造函数创建出来的实例，默认会共享同一个原型对象。

这也是后面方法复用的基础。

图：从控制台结果理解构造函数与原型对象的关系

这张图适合帮助我们建立第一个直觉：构造函数不是孤立存在的，它天然带着一个 prototype 对象。

2. 为什么 p1 和 p2 可以访问同一套原型内容？

function Person() {}

const p1 = new Person()
const p2 = new Person()

这里最值得记住的不是“创建了两个实例”，而是“这两个实例的原型指向同一个地方”。

console.log(Object.getPrototypeOf(p1) === Object.getPrototypeOf(p2)) // true
console.log(Object.getPrototypeOf(p1) === Person.prototype) // true
console.log(Object.getPrototypeOf(p2) === Person.prototype) // true

图：p1 与 p2 实例对象共享同一个原型对象

这就解释了一个很重要的工程现象：

• 改 Person.prototype.xxx
• 实际上影响的是所有还指向这个原型对象的实例

function Person() {}

const p1 = new Person()
const p2 = new Person()

console.log(Object.getPrototypeOf(p1) === Person.prototype) // true
console.log(Object.getPrototypeOf(p2) === Person.prototype) // true

图：通过相等比较验证实例原型是否一致

3. 一个很适合面试和排错的思考题：p1.name 到底能从哪里拿到？

假设 p1 自身没有 name，那 p1.name 还能不能拿到值？

答案是能，而且方式不止一种。本质上，这些方式最终都在改同一个共享原型对象。

function Person() {}

const p1 = new Person()
const p2 = new Person()

Object.getPrototypeOf(p1).name = '小吴'
console.log(p1.name) // 小吴

Person.prototype.name = 'XiaoWu'
console.log(p1.name) // XiaoWu

Object.getPrototypeOf(p2).name = 'why'
console.log(p1.name) // why

为什么第三种改 p2 的原型，也会影响 p1？

因为：

Object.getPrototypeOf(p1) === Object.getPrototypeOf(p2) === Person.prototype

它们最终都指向同一个共享对象。

把这个关系进一步抽象成“内存地址”，就更容易理解了。你可以把上面的变化想成：

// 假设共享原型对象就像一个地址 0x100
0x100.name = '小吴'
console.log(0x100.name) // 小吴

0x100.name = 'XiaoWu'
console.log(0x100.name) // XiaoWu

0x100.name = 'why'
console.log(0x100.name) // why

图：从“内存指向”视角理解实例、构造函数与原型的关系

这个视角非常关键，因为后面理解“共享方法”“重写原型”“原型链继承”时，本质都是在理解引用关系，而不是背结论。

本章小结

• 同一个构造函数创建的实例，默认共享同一个原型对象
• Object.getPrototypeOf(p1) === Person.prototype 是原型学习中的第一条黄金验证公式
• 改共享原型，相当于影响所有还连接到它的实例
• 原型问题一旦抽象成“引用地址”，很多现象都会变得很好解释
• 面试里问“为什么改 p2 的原型会影响 p1”，本质在考你是否理解“共享引用”

四、函数原型上的高频知识点：共享属性与 constructor

前面讲的是“为什么原型存在”，这一节讲“原型上通常放什么”。

1. 原型上放的是“共享能力”

在 JavaScript 中，函数的 prototype 对象，本质上就是给实例共享用的。

function Person() {}

Person.prototype.name = 'why'
Person.prototype.age = 18

const p1 = new Person()
const p2 = new Person()

console.log(p1.name, p2.age) // why 18

这意味着：

• name 和 age 不在 p1、p2 自身上
• 它们来自共享原型
• 所有实例都能访问，但并不各自拷贝一份

图：往原型上添加共享属性后的结构示意

这里顺便给一个工程建议：
如果一个值会因实例不同而不同，就不要放原型上；如果一段行为对所有实例都一致，就优先考虑放原型上。

2. constructor 是什么？为什么平时看不见？

默认情况下，函数的原型对象上会有一个 constructor 属性，它指回构造函数本身。

function Foo() {}

console.log(Foo.prototype.constructor === Foo) // true

但很多同学在控制台直接打印 Foo.prototype 时，看见的是个空对象，于是误以为它什么都没有。其实不是没有，而是：

constructor 默认是不可枚举的。

所以直接打印、遍历时看不明显，但你可以通过属性描述符把它“看见”。

function Foo() {}

console.log(Foo.prototype) // 看起来像 {}
console.log(Object.getOwnPropertyDescriptors(Foo.prototype))

图：在 Node 中查看 constructor 的真实属性描述符

3. constructor 存在的意义是什么？

constructor 的工程意义，不是“让你炫技”，而是帮我们保留一条从原型对象追溯回构造函数的路径。

function Foo() {}

console.log(Foo.prototype.constructor.name) // Foo

这相当于让原型系统形成了一个闭环：

• 实例通过 [[Prototype]] 指向原型对象
• 原型对象通过 constructor 指回构造函数

这条关系能帮助我们做理解、调试和某些类型判断。但也要注意一点：

constructor 可以被改写，所以它不是绝对可靠的类型判断依据。

在工程里，如果你想做类型判断：

• 优先考虑 instanceof
• 或者基于更稳定的品牌判断方式
• 不要把 constructor 当成唯一真理

4. 一个有意思但不建议滥用的闭环验证

function Foo() {}

console.log(
  Foo.prototype.constructor.prototype.constructor.prototype.constructor.name
) // Foo

这段代码能跑通，不是因为 JavaScript 神秘，而是因为这条引用关系本来就存在。
不过知道就好，别把它写进业务代码里。

本章小结

• 原型对象最适合承载共享属性和共享方法
• constructor 默认存在于函数原型对象上，只是不可枚举
• Foo.prototype.constructor === Foo 是默认成立的
• constructor 适合理解原型结构，但不适合作为唯一类型判断依据
• 共享逻辑放原型，是 JavaScript 节省内存、复用能力的关键设计

五、重写原型对象时，为什么最容易踩坑

前面讲的是“给现有原型追加内容”，这一节讲的是另一种更激进的操作：直接重写整个原型对象。

1. 什么叫“重写原型对象”？

不是这样：

Person.prototype.name = '小吴'
Person.prototype.age = 20

而是这样：

function Person() {}

Person.prototype = {
  name: '小吴',
  age: 20,
  learn() {
    console.log(this.name + '在学习')
  }
}

这种写法在属性比较多时很常见，结构也更集中。

先看原始的“构造函数与原型相互关联”视角：

图：默认原型对象与构造函数之间的关联

当你执行 Person.prototype = { ... } 时，本质上是让 Person.prototype 指向了一个全新的对象。

图：重写原型后，构造函数指向了新的原型对象

继续把内容填进去之后，新的结构才完整：

图：新的原型对象被填充内容后的状态

2. 这里最容易掉的坑：constructor 丢了

看下面的代码：

function Person() {}

Person.prototype = {
  name: '小吴',
  age: 18,
  height: 1.88
}

const f1 = new Person()
console.log(f1.name + '今年' + f1.age) // 小吴今年18

功能看起来没问题，但有一个隐藏变化：

console.log(Person.prototype.constructor === Person) // false
console.log(Person.prototype.constructor === Object) // true

原因并不复杂：

• 默认创建函数时，引擎会为它生成一个带 constructor 的原型对象
• 但你手动赋值的新对象只是一个普通对象字面量
• 它自己的 constructor 并不是 Person
• 查找时会沿着这个新对象的原型往上找到 Object.prototype.constructor

图：重写原型后，实例仍能访问属性，但 constructor 关系已发生变化

3. 正确做法：手动把 constructor 补回去

最常见的补法如下：

function Foo() {}

Foo.prototype = {
  name: '小吴',
  age: 18,
  height: 1.88
}

Object.defineProperty(Foo.prototype, 'constructor', {
  enumerable: false,
  writable: true,
  configurable: true,
  value: Foo
})

const f1 = new Foo()
console.log(f1.name + '今年' + f1.age)

为什么不用下面这种简单写法？

Foo.prototype = {
  constructor: Foo,
  name: '小吴'
}

因为这样写出来的 constructor 默认是可枚举的，而原生默认行为里，这个属性应该是不可枚举的。
如果你想尽量保持和原生行为一致，Object.defineProperty 更合适。

图：补回 constructor 后，构造函数与新原型对象重新闭合

4. 再补一个容易忽略的边界条件

很多人以为“重写原型后，旧原型会立即消失”，这其实不严谨。

更准确的说法是：

• 如果旧原型对象已经没有任何可达引用，后续才可能被垃圾回收
• 如果已有实例还指向旧原型，那旧原型仍然活着

例如：

function Person() {}

const oldP = new Person()

Person.prototype = {
  sayHello() {
    console.log('hello')
  }
}

const newP = new Person()

console.log(Object.getPrototypeOf(oldP) === Object.getPrototypeOf(newP)) // false

这在排查“为什么新老实例行为不一致”时非常关键。

本章小结

• 给 prototype 追加属性，和直接重写整个 prototype，是两种不同操作
• 重写原型后，默认的 constructor 关联会丢失
• 推荐用 Object.defineProperty 把 constructor 补回去
• 重写原型不会自动“更新”旧实例的原型指向
• 原型对象是否回收，取决于是否还有引用，而不是“看起来不用了”

六、创建对象的推荐姿势：实例数据放 this，共享方法放 prototype

这是原型章节里最重要的工程落点。

1. 一个典型错误：把实例数据塞进共享原型

下面这段代码看似“想省事”，实则会制造共享数据污染：

function Person(name, age, sex, address) {
  Person.prototype.name = name
  Person.prototype.age = age
  Person.prototype.sex = sex
  Person.prototype.address = address
}

const p1 = new Person('小吴', 18, '男', '福建')
console.log(p1.name) // 小吴

const p2 = new Person('why', 35, '男', '广州')
console.log(p1.name) // why

为什么 p1.name 最后变成了 why？

因为你不是把数据放进 p1、p2 自身，而是放进了它们共享的 Person.prototype。
这等于让所有实例共用一份可变数据，自然后创建的实例会覆盖前一个实例的结果。

这类问题在工程里很致命，因为它会造成一种非常糟糕的现象：对象看起来是独立的，实际状态却是串联的。

2. 正确做法：实例数据归实例，共享方法归原型

function Person(name, age, sex, address) {
  this.name = name
  this.age = age
  this.sex = sex
  this.address = address
}

Person.prototype.eating = function () {
  console.log(this.name + '今天吃烤地瓜了')
}

Person.prototype.running = function () {
  console.log(this.name + '今天跑了五公里')
}

const p1 = new Person('小吴', 18, '男', '福建')
const p2 = new Person('why', 35, '男', '广州')

console.log(p1.name) // 小吴
console.log(p2.name) // why
console.log(p1.eating === p2.eating) // true

这套写法有三个直接收益：

1. 实例数据隔离
   每个对象维护自己的状态，不会相互覆盖

2. 方法共享
   所有实例共用同一个方法引用，减少重复创建

3. 结构清晰
   一眼能分清“对象自己的数据”和“对象共享的行为”

3. 为什么不要把原型方法写进构造函数内部？

有些代码会这么写：

function Person(name) {
  this.name = name
  this.eating = function () {
    console.log(this.name + '在吃东西')
  }
}

它不是不能运行，而是有明显代价：每次 new Person() 都会重新创建一个新的函数对象。

如果实例特别多，这就是实打实的重复内存占用和不必要的函数分配。

更合理的方式还是：

function Person(name) {
  this.name = name
}

Person.prototype.eating = function () {
  console.log(this.name + '在吃东西')
}

4. 这套模式和 class 有什么关系？

如果你已经在写 class，那更应该理解这部分。因为：

class Person {
  constructor(name) {
    this.name = name
  }

  eating() {
    console.log(this.name + '在吃东西')
  }
}

本质上仍然是：

• constructor 里放实例数据
• 方法定义在原型上

class 改变的是写法，不是底层原理。

本章小结

• 实例间不同的数据，放 this
• 所有实例共享的行为，放 prototype
• 不要把可变实例数据放到共享原型上
• 不要在构造函数里重复创建所有实例都相同的方法
• 理解这条原则后，再看 class 会非常顺手

实战建议

1. 代码评审时重点看这几件事

• 是否把实例级数据错误地挂到了原型上
• 是否把共享方法错误地定义在构造函数内部
• 是否在重写 prototype 后忘了补 constructor
• 是否在正式代码里依赖 __proto__ 而不是标准 API
• 是否出现“旧实例”和“新实例”指向不同原型的潜在风险

2. 调试原型问题时，建议这样验证

console.log(Object.getPrototypeOf(obj))
console.log(Object.getPrototypeOf(obj) === Foo.prototype)
console.log(obj.hasOwnProperty('xxx'))
console.log('xxx' in obj)
console.log(Object.getOwnPropertyDescriptors(Foo.prototype))

这一组排查动作，足够覆盖大多数原型相关问题：

• 属性是自己的，还是继承来的
• 当前实例到底连到哪个原型对象
• 原型对象上的属性描述符是否符合预期
• constructor 是否被改坏了

3. 团队内可以落地的约束

• 约定：实例状态一律放 this / 类字段
• 约定：共享方法统一放原型 / 类方法
• 约定：禁止在业务代码里直接依赖 __proto__
• 约定：重写 prototype 必须同步恢复 constructor
• 约定：在 Code Review Checklist 中加入“原型污染”和“共享引用”检查项

4. 性能与可维护性的权衡

• 小量对象场景下，差异可能不明显
• 大量实例场景下，方法是否共享会带来真实内存差异
• 动态改原型虽然灵活，但会明显增加维护成本
• 原型越“魔法化”，后续新人接手成本越高

总结：关键结论与团队落地建议

JavaScript 的原型并不神秘，它本质上解决的是两个问题：

1. 对象找不到属性时，去哪里继续找
2. 多个实例如何共享同一套行为定义

把这两件事想清楚，原型就不再是零散知识点，而是一套完整的对象模型。

最后用几条结论收尾：

• [[Prototype]] 是对象的查找链路，prototype 是构造函数为实例准备的共享模板
• new 的关键一步，是把实例的 [[Prototype]] 指向构造函数的 prototype
• constructor 默认存在于原型对象上，只是不可枚举
• 重写 prototype 会改变后续实例的继承来源，同时可能破坏 constructor
• 最稳妥的工程实践是：实例数据放 this，共享方法放 prototype

如果要在团队内部继续往下沉淀，建议下一步把下面几个主题串起来学习：

• 原型链完整查找过程
• instanceof 的底层判断逻辑
• Object.create 与显式指定原型
• 组合继承、寄生组合继承
• class extends 背后的原型链本质

当你把这些知识连起来之后，JavaScript 的对象系统就不再是“记忆题”，而会变成你分析框架、阅读源码、设计抽象时的一套底层能力。

A firewall is a tool for monitoring and filtering incoming and outgoing network traffic. It works by defining a set of security rules that determine whether to allow or block specific traffic.

Ubuntu ships with a firewall configuration tool called UFW (Uncomplicated Firewall). It is a user-friendly front-end for managing iptables firewall rules. Its main goal is to make managing a firewall easier or, as the name says, uncomplicated.

This article describes how to use the UFW tool to configure and manage a firewall on Ubuntu 24.04. A properly configured firewall is one of the most important aspects of overall system security.

Prerequisites #

Only root or users with sudo privileges can manage the system firewall. The best practice is to run administrative tasks as a sudo user.

Install UFW #

UFW is part of the standard Ubuntu 24.04 installation and should be present on your system. If for some reason it is not installed, you can install the package by typing:

sudo apt update
sudo apt install ufw

Check UFW Status #

UFW is disabled by default. You can check the status of the UFW service with the following command:

sudo ufw status verbose

The output will show that the firewall status is inactive:

Status: inactive

If UFW is activated, the output will look something like the following:

Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), disabled (routed)
New profiles: skip

UFW Default Policies #

The default behavior of the UFW firewall is to block all incoming and forwarding traffic and allow all outbound traffic. This means that anyone trying to access your server will not be able to connect unless you specifically open the port. Applications and services running on your server will be able to access the outside world.

The default policies are defined in the /etc/default/ufw file and can be changed either by manually modifying the file or with the sudo ufw default <policy> <chain> command.

Firewall policies are the foundation for building more complex and user-defined rules. Generally, the initial UFW default policies are a good starting point.

Application Profiles #

An application profile is a text file in INI format that describes the service and contains firewall rules for the service. Application profiles are created in the /etc/ufw/applications.d directory during the installation of the package.

You can list all application profiles available on your server by typing:

sudo ufw app list

Depending on the packages installed on your system, the output will look similar to the following:

Available applications:
Nginx Full
Nginx HTTP
Nginx HTTPS
OpenSSH

To find more information about a specific profile and included rules, use the following command:

sudo ufw app info 'Nginx Full'

The output shows that the ‘Nginx Full’ profile opens ports 80 and 443.

Profile: Nginx Full
Title: Web Server (Nginx, HTTP + HTTPS)
Description: Small, but very powerful and efficient web server
Ports:
80,443/tcp

You can also create custom profiles for your applications.

Enabling UFW #

If you are connecting to your Ubuntu server from a remote location, before enabling the UFW firewall you must explicitly allow incoming SSH connections. Otherwise, you will no longer be able to connect to the machine.

To configure your UFW firewall to allow incoming SSH connections, type the following command:

sudo ufw allow ssh

Rules updated
Rules updated (v6)

If SSH is running on a non-standard port , you need to open that port.

For example, if your ssh daemon listens on port 7722, enter the following command to allow connections on that port:

sudo ufw allow 7722/tcp

Now that the firewall is configured to allow incoming SSH connections, you can enable it by typing:

sudo ufw enable

Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

You will be warned that enabling the firewall may disrupt existing ssh connections; type y and hit Enter.

Opening Ports #

Depending on the applications that run on the system, you may also need to open other ports. The general syntax to open a port is as follows:

ufw allow port_number/protocol

Below are a few ways to allow HTTP connections.

The first option is to use the service name. UFW checks the /etc/services file for the port and protocol of the specified service:

sudo ufw allow http

You can also specify the port number and the protocol:

sudo ufw allow 80/tcp

When no protocol is given, UFW creates rules for both tcp and udp.

Another option is to use the application profile; in this case, ‘Nginx HTTP’:

sudo ufw allow 'Nginx HTTP'

UFW also supports another syntax for specifying the protocol using the proto keyword:

sudo ufw allow proto tcp to any port 80

Port Ranges #

UFW also allows you to open port ranges. The start and the end ports are separated by a colon (:), and you must specify the protocol, either tcp or udp.

For example, if you want to allow ports from 7100 to 7200 on both tcp and udp, run the following commands:

sudo ufw allow 7100:7200/tcp
sudo ufw allow 7100:7200/udp

Specific IP Address and Port #

To allow connections on all ports from a given source IP, use the from keyword followed by the source address.

Here is an example of allowlisting an IP address:

sudo ufw allow from 64.63.62.61

If you want to allow the given IP address access only to a specific port, use the to any port keyword followed by the port number.

For example, to allow access on port 22 from a machine with IP address 64.63.62.61, enter:

sudo ufw allow from 64.63.62.61 to any port 22

Subnets #

The syntax for allowing connections to a subnet of IP addresses is the same as when using a single IP address. The only difference is that you need to specify the netmask.

Below is an example showing how to allow access for IP addresses ranging from 192.168.1.1 to 192.168.1.254 to port 3306 (MySQL):

sudo ufw allow from 192.168.1.0/24 to any port 3306

Specific Network Interface #

To allow connections on a particular network interface, use the in on keyword followed by the name of the network interface:

sudo ufw allow in on eth2 to any port 3306

Denying Connections #

The default policy for all incoming connections is set to deny, and if you have not changed it, UFW will block all incoming connections unless you specifically open the connection.

Writing deny rules is the same as writing allow rules; you only need to use the deny keyword instead of allow.

Say you opened ports 80 and 443, and your server is under attack from the 23.24.25.0/24 network. To deny all connections from that network, run:

sudo ufw deny from 23.24.25.0/24

To deny access only to ports 80 and 443 from 23.24.25.0/24, use the following command:

sudo ufw deny proto tcp from 23.24.25.0/24 to any port 80,443

Deleting UFW Rules #

There are two ways to delete UFW rules: by rule number, and by specifying the actual rule.

Deleting rules by rule number is easier, especially when you are new to UFW. To delete a rule by number, first find the number of the rule you want to delete. To get a list of numbered rules, use the ufw status numbered command:

sudo ufw status numbered

Status: active
To Action From
-- ------ ----
[ 1] 22/tcp ALLOW IN Anywhere
[ 2] 80/tcp ALLOW IN Anywhere
[ 3] 8080/tcp ALLOW IN Anywhere

To delete rule number 3, the one that allows connections to port 8080, enter:

sudo ufw delete 3

The second method is to delete a rule by specifying the actual rule. For example, if you added a rule to open port 8069 you can delete it with:

sudo ufw delete allow 8069

Disabling UFW #

If you want to stop UFW and deactivate all the rules, use:

sudo ufw disable

To re-enable UFW and activate all rules, type:

sudo ufw enable

Resetting UFW #

Resetting UFW will disable it and delete all active rules. This is helpful if you want to revert all your changes and start fresh.

To reset UFW, run the following command:

sudo ufw reset

IP Masquerading #

IP Masquerading is a variant of NAT (network address translation) in the Linux kernel that translates network traffic by rewriting the source and destination IP addresses and ports. With IP Masquerading, you can allow one or more machines in a private network to communicate with the internet using one Linux machine that acts as a gateway.

Configuring IP Masquerading with UFW involves several steps.

First, you need to enable IP forwarding. To do that, open the /etc/ufw/sysctl.conf file:

sudo nano /etc/ufw/sysctl.conf

Find and uncomment the line which reads net.ipv4.ip_forward=1:

net.ipv4.ip_forward=1

Next, you need to configure UFW to allow forwarded packets. Open the UFW configuration file:

sudo nano /etc/default/ufw

Locate the DEFAULT_FORWARD_POLICY key, and change the value from DROP to ACCEPT:

DEFAULT_FORWARD_POLICY="ACCEPT"

Now you need to set the default policy for the POSTROUTING chain in the nat table and the masquerade rule. To do so, open the /etc/ufw/before.rules file:

sudo nano /etc/ufw/before.rules

Append the following lines:

#NAT table rules
*nat
:POSTROUTING ACCEPT [0:0]

# Forward traffic through eth0 - Change to public network interface
-A POSTROUTING -s 10.8.0.0/16 -o eth0 -j MASQUERADE

# don't delete the 'COMMIT' line or these rules won't be processed
COMMIT

Replace eth0 in the -A POSTROUTING line with the name of your public network interface.

When you are done, save and close the file. Finally, reload the UFW rules:

sudo ufw disable
sudo ufw enable

Troubleshooting #

UFW blocks SSH after enabling it
If you enabled UFW without first allowing SSH, you will lose access to a remote server. To recover, you need console access (via your hosting provider’s web console) and run sudo ufw allow ssh followed by sudo ufw enable. Always allow SSH before enabling UFW on a remote machine.

Rules not active after ufw reset
After a reset, UFW is disabled and all rules are cleared. You need to re-add your rules and run sudo ufw enable to bring the firewall back up.

IPv6 rules not created
If ufw status shows rules only for IPv4, check that IPV6=yes is set in /etc/default/ufw, then run sudo ufw disable && sudo ufw enable to reload the configuration.

Application profile not found
If sudo ufw allow 'Nginx Full' returns an error, the profile may not be installed yet. Install the relevant package first (for example, nginx), then retry.

Conclusion #

We have shown you how to install and configure a UFW firewall on your Ubuntu 24.04 server. For a full reference of UFW commands and options, see the UFW man page .

背景

上个月，团队决定开拓新链，启动了一个基于Solana的NFT铸造项目。作为团队里Web3前端经验相对丰富的，我自然被分配了搭建前端DApp的任务。我之前主要深耕以太坊和EVM兼容链，对ethers.js、wagmi那一套滚瓜烂熟，心想换个链的SDK能有多难？结果，从熟悉的ethers.providers.Web3Provider切换到@solana/web3.js的Connection类，从MetaMask切换到Phantom钱包，这一路的“水土不服”让我踩的坑比预想的多得多。我的首要目标很简单：让用户能用Phantom钱包连接，并正确显示其SOL余额。

问题分析

一开始，我试图沿用EVM链的思维模式。在以太坊上，流程通常是：注入的window.ethereum -> new ethers.providers.Web3Provider() -> 获取账号和余额。我查了@solana/web3.js的文档，发现核心是Connection（连接节点）和PublicKey（地址）。我的初步思路是：

1. 检测Phantom钱包（window.solana）。
2. 连接钱包，获取公钥（PublicKey）。
3. 用Connection查询该公钥的余额。

听起来很直接，但我马上遇到了第一个拦路虎：连接钱包后，余额始终为0。我确认了钱包里有SOL，RPC节点也换了好几个（devnet, mainnet-beta的公共节点）。排查后发现，问题出在两个地方：一是对Solana余额单位（lamports vs SOL）的转换不熟悉，二是没有正确处理钱包连接和状态变化的异步事件。这让我意识到，不能简单照搬EVM的模式，得从头理解Solana前端的交互逻辑。

核心实现

1. 环境搭建与钱包检测

首先，创建一个React + TypeScript项目，并安装核心依赖：

npm install @solana/web3.js @solana/wallet-adapter-base @solana/wallet-adapter-react @solana/wallet-adapter-react-ui @solana/wallet-adapter-wallets @solana/wallet-adapter-phantom

这里有个关键点：单纯用@solana/web3.js也能直接操作window.solana，但社区更推荐使用@solana/wallet-adapter-*这一套工具库。它提供了React上下文、钩子和一套标准的UI组件，能更好地管理钱包状态、支持多钱包，并处理了大量底层细节。我决定采用这个推荐方案，避免重复造轮子。

钱包检测和连接的核心逻辑，我们封装在自定义钩子或上下文中。但首先，要在应用根组件进行配置。

2. 配置钱包上下文与连接节点

在App.tsx或主组件中，我们需要设置钱包适配器和提供连接。

// App.tsx
import React, { useMemo } from 'react';
import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { PhantomWalletAdapter } from '@solana/wallet-adapter-phantom';
import { WalletModalProvider } from '@solana/wallet-adapter-react-ui';
import { clusterApiUrl } from '@solana/web3.js';

// 导入默认样式
import '@solana/wallet-adapter-react-ui/styles.css';

function App() {
  // 配置网络。这里以开发网为例，上线需切主网
  const network = WalletAdapterNetwork.Devnet;
  // 使用Memoized，避免每次渲染都创建新的endpoint和wallets实例
  const endpoint = useMemo(() => clusterApiUrl(network), [network]);
  
  const wallets = useMemo(
    () => [
      new PhantomWalletAdapter(),
      // 可以添加其他钱包适配器，如Solflare
    ],
    []
  );

  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={wallets} autoConnect>
        <WalletModalProvider>
          {/* 你的应用组件 */}
          <MyWalletComponent />
        </WalletModalProvider>
      </WalletProvider>
    </ConnectionProvider>
  );
}

export default App;

注意这个细节：ConnectionProvider的endpoint参数非常重要。公共节点可能有速率限制或不稳定，对于生产环境，强烈建议使用付费的RPC服务（如QuickNode, Helius）提供的专属节点URL，这能极大提升连接稳定性和查询速度。

3. 连接钱包与获取余额

接下来，在具体的组件MyWalletComponent中，我们使用适配器提供的钩子来操作钱包和获取数据。

// components/MyWalletComponent.tsx
import React, { useEffect, useState } from 'react';
import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { LAMPORTS_PER_SOL } from '@solana/web3.js';
import { WalletMultiButton } from '@solana/wallet-adapter-react-ui';

export const MyWalletComponent: React.FC = () => {
  const { connection } = useConnection();
  const { publicKey, connected } = useWallet();
  const [balance, setBalance] = useState<number | null>(null);
  const [loading, setLoading] = useState(false);

  // 效果：当钱包连接状态或公钥变化时，获取余额
  useEffect(() => {
    const fetchBalance = async () => {
      if (!connection || !publicKey) {
        setBalance(null);
        return;
      }
      setLoading(true);
      try {
        // 这里有个坑：getBalance返回的是lamports（1 SOL = 10^9 lamports）
        const lamportsBalance = await connection.getBalance(publicKey);
        // 转换为SOL单位
        const solBalance = lamportsBalance / LAMPORTS_PER_SOL;
        setBalance(solBalance);
      } catch (error) {
        console.error('获取余额失败:', error);
        setBalance(null);
      } finally {
        setLoading(false);
      }
    };

    fetchBalance();
    // 可以设置一个定时器来轮询余额，但对于实时性要求高的，建议用websocket订阅
  }, [connection, publicKey]); // 依赖项：连接对象和公钥

  return (
    <div>
      <WalletMultiButton />
      {connected && publicKey ? (
        <div>
          <p>钱包地址: {publicKey.toBase58()}</p>
          {loading ? (
            <p>查询余额中...</p>
          ) : (
            <p>余额: {balance !== null ? `${balance.toFixed(4)} SOL` : '--'}</p>
          )}
        </div>
      ) : (
        <p>请连接钱包</p>
      )}
    </div>
  );
};

这里有个大坑：connection.getBalance(publicKey)返回的是number类型的lamports，而不是SOL。直接显示这个数字会让人误以为余额极小。必须除以LAMPORTS_PER_SOL（一个常量，值为1_000_000_000）来转换。这是我一开始显示余额为0的罪魁祸首之一（因为我的devnet账户余额是2 SOL，显示为2_000_000_000 lamports，我误以为是0）。

4. 构造并发送一笔简单的转账交易

显示余额之后，下一步自然是想让用户能操作。我们实现一个简单的SOL转账功能。

// 在MyWalletComponent中添加状态和函数
import { SystemProgram, Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
// ... 其他导入

export const MyWalletComponent: React.FC = () => {
  // ... 之前的 states 和 hooks
  const [recipient, setRecipient] = useState('');
  const [amount, setAmount] = useState('');
  const [sending, setSending] = useState(false);

  const handleSendSol = async () => {
    if (!publicKey || !recipient || !amount) {
      alert('请填写完整信息');
      return;
    }
    const lamports = parseFloat(amount) * LAMPORTS_PER_SOL;
    if (isNaN(lamports) || lamports <= 0) {
      alert('请输入有效的金额');
      return;
    }

    setSending(true);
    try {
      // 1. 创建交易对象
      const transaction = new Transaction();
      
      // 2. 添加转账指令
      const transferInstruction = SystemProgram.transfer({
        fromPubkey: publicKey,
        toPubkey: new PublicKey(recipient),
        lamports,
      });
      transaction.add(transferInstruction);

      // 3. 获取最近的区块哈希（Recent Blockhash），这是Solana交易必需的
      const { blockhash } = await connection.getRecentBlockhash();
      transaction.recentBlockhash = blockhash;
      // 设置付费方（fee payer）
      transaction.feePayer = publicKey;

      // 4. 发送交易并等待确认
      // 注意：这里需要钱包适配器来签名，不能直接用sendAndConfirmTransaction
      // 我们先获取签名，然后发送
      const signature = await sendTransaction(transaction, connection);
      
      // 5. 等待确认（可选，对于快速反馈，可以只等“预确认”）
      await connection.confirmTransaction(signature, 'confirmed');
      alert(`转账成功！交易哈希: ${signature}`);
      // 成功后刷新余额
      const newBalance = await connection.getBalance(publicKey);
      setBalance(newBalance / LAMPORTS_PER_SOL);
      setRecipient('');
      setAmount('');
    } catch (error: any) {
      console.error('转账失败:', error);
      alert(`转账失败: ${error.message}`);
    } finally {
      setSending(false);
    }
  };

  // 注意：我们需要从useWallet钩子中解构出sendTransaction函数
  const { sendTransaction } = useWallet();

  return (
    <div>
      {/* ... 之前的连接和余额显示代码 */}
      {connected && (
        <div>
          <h3>转账SOL</h3>
          <input
            type="text"
            placeholder="接收方地址"
            value={recipient}
            onChange={(e) => setRecipient(e.target.value)}
          />
          <input
            type="number"
            step="any"
            placeholder="金额 (SOL)"
            value={amount}
            onChange={(e) => setAmount(e.target.value)}
          />
          <button onClick={handleSendSol} disabled={sending}>
            {sending ? '发送中...' : '发送'}
          </button>
        </div>
      )}
    </div>
  );
};

这里有个至关重要的区别：在EVM链，我们通常用signer.sendTransaction(tx)一步完成签名和发送。而在Solana，构造交易（Transaction）和签名/发送是分离的。我们先用@solana/web3.js构造一个包含指令（Instruction）和必要元数据（blockhash, feePayer）的交易对象，然后通过钱包适配器提供的sendTransaction方法，将交易对象交给钱包（如Phantom）去签名并发送到网络。这是Solana交易模型的一个核心特点。

完整代码

以下是一个整合后的、可直接运行的简化版App.tsx，展示了完整的连接、查余额、转账流程。

// App.tsx
import React, { useMemo, useState, useEffect } from 'react';
import { ConnectionProvider, WalletProvider, useConnection, useWallet } from '@solana/wallet-adapter-react';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { PhantomWalletAdapter } from '@solana/wallet-adapter-phantom';
import { WalletModalProvider, WalletMultiButton } from '@solana/wallet-adapter-react-ui';
import { clusterApiUrl, PublicKey, SystemProgram, Transaction, LAMPORTS_PER_SOL } from '@solana/web3.js';
import '@solana/wallet-adapter-react-ui/styles.css';

// 主应用包装器
function AppWrapper() {
  const network = WalletAdapterNetwork.Devnet;
  const endpoint = useMemo(() => clusterApiUrl(network), [network]);
  const wallets = useMemo(() => [new PhantomWalletAdapter()], []);

  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={wallets} autoConnect>
        <WalletModalProvider>
          <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
            <h1>Solana Web3.js 入门实战</h1>
            <WalletDemo />
          </div>
        </WalletModalProvider>
      </WalletProvider>
    </ConnectionProvider>
  );
}

// 主要演示组件
function WalletDemo() {
  const { connection } = useConnection();
  const { publicKey, connected, sendTransaction } = useWallet();
  const [balance, setBalance] = useState<number | null>(null);
  const [loading, setLoading] = useState(false);
  const [recipient, setRecipient] = useState('');
  const [amount, setAmount] = useState('');
  const [sending, setSending] = useState(false);

  // 获取余额
  useEffect(() => {
    const updateBalance = async () => {
      if (!connection || !publicKey) {
        setBalance(null);
        return;
      }
      setLoading(true);
      try {
        const lamports = await connection.getBalance(publicKey);
        setBalance(lamports / LAMPORTS_PER_SOL);
      } catch (err) {
        console.error(err);
        setBalance(null);
      } finally {
        setLoading(false);
      }
    };
    updateBalance();
  }, [connection, publicKey]);

  // 处理转账
  const handleSend = async () => {
    if (!publicKey || !recipient || !amount || !sendTransaction) return;
    const lamports = parseFloat(amount) * LAMPORTS_PER_SOL;
    if (isNaN(lamports) || lamports <= 0) {
      alert('Invalid amount');
      return;
    }

    setSending(true);
    try {
      const transaction = new Transaction();
      transaction.add(
        SystemProgram.transfer({
          fromPubkey: publicKey,
          toPubkey: new PublicKey(recipient),
          lamports,
        })
      );

      const { blockhash } = await connection.getRecentBlockhash();
      transaction.recentBlockhash = blockhash;
      transaction.feePayer = publicKey;

      const signature = await sendTransaction(transaction, connection);
      console.log('Transaction signature:', signature);
      // 等待确认，可根据需求调整确认级别（'processed', 'confirmed', 'finalized'）
      await connection.confirmTransaction(signature, 'confirmed');
      alert(`Sent ${amount} SOL to ${recipient}! Tx: ${signature}`);

      // 刷新余额
      const newLamports = await connection.getBalance(publicKey);
      setBalance(newLamports / LAMPORTS_PER_SOL);
      setRecipient('');
      setAmount('');
    } catch (error: any) {
      console.error('Send failed:', error);
      alert(`Send failed: ${error.message}`);
    } finally {
      setSending(false);
    }
  };

  return (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <WalletMultiButton />
      </div>

      {connected && publicKey ? (
        <div>
          <p>
            <strong>Address:</strong> {publicKey.toBase58().slice(0, 8)}...
          </p>
          <p>
            <strong>Balance:</strong>{' '}
            {loading ? 'Loading...' : balance !== null ? `${balance.toFixed(4)} SOL` : '--'}
          </p>

          <div style={{ marginTop: '30px', borderTop: '1px solid #ccc', paddingTop: '20px' }}>
            <h3>Transfer SOL</h3>
            <div style={{ display: 'flex', flexDirection: 'column', gap: '10px', maxWidth: '400px' }}>
              <input
                type="text"
                placeholder="Recipient Public Key"
                value={recipient}
                onChange={(e) => setRecipient(e.target.value)}
                style={{ padding: '8px' }}
              />
              <input
                type="number"
                step="any"
                placeholder="Amount (SOL)"
                value={amount}
                onChange={(e) => setAmount(e.target.value)}
                style={{ padding: '8px' }}
              />
              <button onClick={handleSend} disabled={sending} style={{ padding: '10px' }}>
                {sending ? 'Sending...' : 'Send'}
              </button>
            </div>
            <p style={{ fontSize: '0.9em', color: '#666', marginTop: '10px' }}>
              <small>Use devnet SOL for testing. Get some from a faucet.</small>
            </p>
          </div>
        </div>
      ) : (
        <p>Connect your wallet to get started.</p>
      )}
    </div>
  );
}

export default AppWrapper;

踩坑记录

1. 余额显示为0或极小值：这是最经典的坑。connection.getBalance()返回的是lamports，我没做转换就直接显示。解决方法：牢记 SOL = lamports / LAMPORTS_PER_SOL。
2. 交易发送失败：Missing recent blockhash：构造交易对象Transaction后，没有设置recentBlockhash和feePayer属性就直接发送。解决方法：必须在发送前调用connection.getRecentBlockhash()获取，并赋值给transaction.recentBlockhash，同时明确指定transaction.feePayer。
3. Phantom钱包弹窗连接后，状态没更新：直接监听window.solana的connect事件，但React状态管理混乱。解决方法：使用@solana/wallet-adapter-react提供的useWallet钩子，它封装了状态管理，connected和publicKey状态会自动更新。
4. sendTransaction is not a function：我试图直接从@solana/web3.js导入sendAndConfirmTransaction并传入交易对象，但这需要私钥签名者。在浏览器前端，私钥由钱包保管。解决方法：使用从useWallet()钩子解构出来的sendTransaction方法，它将交易发送到钱包扩展进行签名。

小结

这一趟下来，我最大的收获是理解了Solana前端交互的“范式转换”：从EVM的Provider/Signer模型，转向Solana的Connection/Transaction/Wallet Adapter模型。核心在于明确职责分离：前端构造交易，钱包负责签名。掌握了连接、查余额、转账这三板斧，就算在Solana前端开发中站稳了脚跟。接下来，可以继续深挖如何与智能合约（Solana叫Program）交互，比如调用一个NFT铸造的指令，那又会涉及到不同的指令构造和账户（Account）管理，将是下一个有趣的挑战。

引言

在 React 开发中，Hooks 已经成为状态管理和逻辑复用的核心工具。除了 React 内置的 Hooks，自定义 Hooks 让我们能够将组件逻辑提取到可重用的函数中，实现更好的代码组织和复用。

今天我们来深入探讨自定义 Hooks 的封装技巧，并通过一个实用的 useLocalStorage Hook 来演示如何构建高质量的自定义 Hooks。

自定义 Hooks 的核心原则

1. 命名规范

自定义 Hooks 必须以 use 开头，这是 React 的硬性要求，也是代码可读性的保障：

// ✅ 正确
const useLocalStorage = (key, initialValue) => { ... }
const useFetch = (url) => { ... }
const useDebounce = (value, delay) => { ... }

// ❌ 错误
const localStorageHook = (key, initialValue) => { ... }
const fetchData = (url) => { ... }

2. 单一职责

每个自定义 Hooks 应该只负责一件事，保持逻辑清晰：

// ✅ 好的设计：每个 Hook 职责单一
const { user } = useAuth();
const { data } = useFetch('/api/user');
const { theme } = useTheme();

// ❌ 避免：一个 Hook 做太多事
const useEverything = () => {
  // 认证 + 数据获取 + 主题管理...
}

3. 返回值设计

返回清晰的接口，优先使用对象解构：

// ✅ 清晰的返回值
const { value, setValue, removeValue } = useLocalStorage('key', 'default');

// ✅ 多个返回值时用数组
const [count, setCount] = useCounter(0);

实战：useLocalStorage Hook

基础实现

useLocalStorage 是最常用的自定义 Hooks 之一，它让本地存储变得简单优雅：

import { useState, useEffect } from 'react';

function useLocalStorage(key, initialValue) {
  // 读取初始值
  const readValue = () => {
    if (typeof window === 'undefined') {
      return initialValue;
    }

    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.warn(`Error reading localStorage key "${key}":`, error);
      return initialValue;
    }
  };

  // 使用 lazy initialization
  const [storedValue, setStoredValue] = useState(readValue);

  // 监听其他标签页的变化
  useEffect(() => {
    const handleStorageChange = (event) => {
      if (event.key === key && event.newValue !== null) {
        try {
          setStoredValue(JSON.parse(event.newValue));
        } catch (error) {
          console.warn('Error parsing storage event:', error);
        }
      }
    };

    window.addEventListener('storage', handleStorageChange);
    return () => window.removeEventListener('storage', handleStorageChange);
  }, [key]);

  // 返回包装的 setter
  const setValue = (value) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);
      
      if (typeof window !== 'undefined') {
        window.localStorage.setItem(key, JSON.stringify(valueToStore));
        // 触发当前标签页的事件
        window.dispatchEvent(new Event('local-storage'));
      }
    } catch (error) {
      console.warn(`Error setting localStorage key "${key}":`, error);
    }
  };

  const removeValue = () => {
    try {
      setStoredValue(initialValue);
      if (typeof window !== 'undefined') {
        window.localStorage.removeItem(key);
        window.dispatchEvent(new Event('local-storage'));
      }
    } catch (error) {
      console.warn(`Error removing localStorage key "${key}":`, error);
    }
  };

  return [storedValue, setValue, removeValue];
}

export default useLocalStorage;

使用示例

import useLocalStorage from './hooks/useLocalStorage';

function UserProfile() {
  const [theme, setTheme] = useLocalStorage('theme', 'light');
  const [user, setUser] = useLocalStorage('user', null);

  const toggleTheme = () => {
    setTheme(prev => prev === 'light' ? 'dark' : 'light');
  };

  const logout = () => {
    setUser(null);
  };

  return (
    <div className={`app ${theme}`}>
      <button onClick={toggleTheme}>
        切换到{theme === 'light' ? '深色' : '浅色'}模式
      </button>
      
      {user ? (
        <div>
          <p>欢迎，{user.name}!</p>
          <button onClick={logout}>退出登录</button>
        </div>
      ) : (
        <button onClick={() => setUser({ name: '访客' })}>
          模拟登录
        </button>
      )}
    </div>
  );
}

进阶：添加类型安全（TypeScript 版本）

import { useState, useEffect, Dispatch, SetStateAction } from 'react';

type SetValue<T> = Dispatch<SetStateAction<T>>;

function useLocalStorage<T>(key: string, initialValue: T): [T, SetValue<T>, () => void] {
  const readValue = (): T => {
    if (typeof window === 'undefined') {
      return initialValue;
    }

    try {
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    } catch (error) {
      console.warn(`Error reading localStorage key "${key}":`, error);
      return initialValue;
    }
  };

  const [storedValue, setStoredValue] = useState<T>(readValue);

  useEffect(() => {
    const handleStorageChange = (event: StorageEvent) => {
      if (event.key === key && event.newValue !== null) {
        try {
          setStoredValue(JSON.parse(event.newValue) as T);
        } catch (error) {
          console.warn('Error parsing storage event:', error);
        }
      }
    };

    window.addEventListener('storage', handleStorageChange);
    return () => window.removeEventListener('storage', handleStorageChange);
  }, [key]);

  const setValue: SetValue<T> = (value) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);
      
      if (typeof window !== 'undefined') {
        window.localStorage.setItem(key, JSON.stringify(valueToStore));
        window.dispatchEvent(new Event('local-storage'));
      }
    } catch (error) {
      console.warn(`Error setting localStorage key "${key}":`, error);
    }
  };

  const removeValue = () => {
    try {
      setStoredValue(initialValue);
      if (typeof window !== 'undefined') {
        window.localStorage.removeItem(key);
        window.dispatchEvent(new Event('local-storage'));
      }
    } catch (error) {
      console.warn(`Error removing localStorage key "${key}":`, error);
    }
  };

  return [storedValue, setValue, removeValue];
}

export default useLocalStorage;

封装技巧总结

1. SSR 兼容：始终检查 window 是否存在
2. 错误处理：用 try-catch 包裹 localStorage 操作
3. 事件同步：监听 storage 事件实现多标签页同步
4. 函数式更新：支持传入函数进行状态更新
5. 类型安全：使用泛型提供完整的 TypeScript 支持

总结

自定义 Hooks 是 React 逻辑复用的强大工具。通过遵循命名规范、保持单一职责、设计清晰的返回值，我们可以构建出易于理解和维护的 Hooks。

useLocalStorage 作为一个经典案例，展示了如何处理浏览器 API、错误边界、跨标签页同步等实际问题。在下篇中，我们将继续探索 useFetch、useDebounce、useInterval 等更多实用的自定义 Hooks。

每个前端项目的根目录下几乎都有一个 package.json，但你真的了解它的每个字段吗？本文将从基础字段到高级配置，逐一拆解 package.json 中的所有字段，帮你彻底搞懂它。

一、必填字段

1.1 name — 包名

{
  "name": "@packageName/sdk"
}

规则：

• 长度不超过 214 个字符
• 不能以 . 或 _ 开头
• 不能包含大写字母
• 不能包含 URL 不安全字符（如空格、~ 等）
• 支持 scope（作用域），格式为 @scope/name，常用于组织级别的包管理，例如 @vue/cli、@babel/core

作用：
name 是包的唯一标识符。当你执行 npm install xxx 时，xxx 就是这个字段的值。配合 version，它们共同构成了包的"身份证"。

1.2 version — 版本号

{
  "version": "1.6.7"
}

必须遵循 Semantic Versioning（语义化版本） 规范，格式为 MAJOR.MINOR.PATCH：

还支持预发布标签：1.0.0-alpha.1、1.0.0-beta.2、1.0.0-rc.1

二、描述信息字段

2.1 description — 包描述

{
  "description": "packageDescription"
}

简短描述包的功能，会展示在 npm search 的搜索结果中，也是 npm 官网搜索排序的权重因子之一。

2.2 keywords — 关键词

{
  "keywords": ["cloud", "sdk", "vue", "plugin", "micro-frontend"]
}

字符串数组，用于 npm 官网的搜索优化（SEO），帮助其他开发者更快找到你的包。

2.3 homepage — 项目主页

{
  "homepage": "https://github.com/user/project#readme"
}

项目官网或文档地址，会展示在 npm 包详情页的侧边栏。

2.4 bugs — Bug 反馈地址

{
  "bugs": {
    "url": "https://github.com/user/project/issues",
    "email": "bugs@example.com"
  }
}

也可以简写为字符串："bugs": "https://github.com/user/project/issues"。

2.5 license — 开源协议

{
  "license": "MIT"
}

常见协议：

2.6 author — 作者

{
  "author": {
    "name": "张三",
    "email": "zhangsan@example.com",
    "url": "https://zhangsan.dev"
  }
}

也支持简写形式："author": "张三 <zhangsan@example.com> (https://zhangsan.dev)"

2.7 contributors — 贡献者

{
  "contributors": [
    { "name": "李四", "email": "lisi@example.com" },
    "王五 <wangwu@example.com>"
  ]
}

格式同 author，是一个数组。

2.8 funding — 赞助信息

{
  "funding": {
    "type": "opencollective",
    "url": "https://opencollective.com/project"
  }
}

也支持数组形式，用于声明多个赞助渠道。执行 npm fund 可查看项目的赞助信息。

三、入口文件字段

这是 package.json 中最核心也最容易混淆的一组字段，直接决定了别人引用你的包时，加载的是哪个文件。

3.1 main — CommonJS 入口

{
  "main": "dist/cloud-sdk.umd.js"
}

作用：
Node.js 和旧版打包工具默认读取的入口。当执行 require('your-package') 时，实际加载的就是 main 指向的文件。

3.2 module — ESModule 入口

{
  "module": "dist/cloud-sdk.esm.js"
}

作用：
这不是 Node.js 官方字段，而是由打包工具（Webpack、Rollup、Vite）约定的。当打包工具发现 module 字段时，会优先使用它，因为 ESM 格式支持 Tree Shaking，能有效减小打包体积。

3.3 browser — 浏览器入口

{
  "browser": "dist/cloud-sdk.browser.js"
}

当包需要在浏览器中运行，且浏览器版本与 Node 版本实现不同时使用。打包工具在构建浏览器端代码时会优先读取此字段。

也支持对象形式，用于替换特定模块：

{
  "browser": {
    "./lib/server-utils.js": "./lib/browser-utils.js",
    "fs": false
  }
}

3.4 types / typings — TypeScript 类型入口

{
  "types": "dist/index.d.ts"
}

指定 TypeScript 类型声明文件的入口路径。types 和 typings 等价，推荐用 types。

3.5 exports — 条件导出（重点！）

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/cloud-sdk.esm.js",
      "require": "./dist/cloud-sdk.umd.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.esm.js",
      "require": "./dist/utils.cjs.js"
    }
  }
}

这是 Node.js 12.11+ 引入的现代模块解析方案，是 main、module、browser 的"终极替代方案"。

核心能力：

条件匹配的优先级（从上到下）：

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "node": {
        "import": "./dist/node.mjs",
        "require": "./dist/node.cjs"
      },
      "browser": "./dist/browser.js",
      "default": "./dist/index.js"
    }
  }
}

注意： types 条件必须放在最前面，否则 TypeScript 可能无法正确解析类型。

3.6 type — 模块系统声明

{
  "type": "module"
}

设置为 "module" 后：

• .js → ESM
• .cjs → CommonJS（强制）
• .mjs → ESM（强制）

四、文件管控字段

4.1 files — 发布包含的文件

{
  "files": ["dist", "README.md", "LICENSE"]
}

白名单机制，指定 npm publish 时需要包含的文件和目录。类似 .gitignore 的反向操作。

始终包含的文件（无法排除）：

• package.json
• README（任何大小写和扩展名）
• LICENSE / LICENCE
• CHANGELOG
• main 字段指向的文件

始终排除的文件（无法包含）：

• .git
• node_modules
• .npmrc
• package-lock.json

技巧： 也可以用 .npmignore 做黑名单控制，但 files 字段优先级更高，两者同时存在时以 files 为准。

4.2 directories — 项目目录结构

{
  "directories": {
    "lib": "src/lib",
    "bin": "bin",
    "man": "man",
    "doc": "docs",
    "example": "examples",
    "test": "test"
  }
}

声明项目的目录结构。实际使用较少，主要是一种语义化描述。

五、脚本与命令字段

5.1 scripts — NPM 脚本

{
  "scripts": {
    "dev": "vite build --watch",
    "build": "vite build",
    "lint": "eslint src",
    "lint:fix": "eslint src --fix",
    "format": "prettier --write src",
    "prepare": "husky install",
    "preinstall": "npx only-allow pnpm"
  }
}

通过 npm run <script-name> 执行。部分脚本名有特殊含义：

生命周期脚本：

pre/post 钩子：

任何自定义脚本都可以加 pre / post 前缀：

{
  "scripts": {
    "prebuild": "rimraf dist",
    "build": "vite build",
    "postbuild": "echo 构建完成"
  }
}

执行 npm run build 会依次执行：prebuild → build → postbuild。

注意： pnpm 和 yarn 现代版本默认不会自动执行 pre/post 钩子，需手动配置开启。

5.2 bin — 可执行文件

{
  "bin": {
    "create-uver": "./bin/create.js"
  }
}

当用户全局安装（npm install -g）或通过 npx 执行时，系统会创建软链接到 bin 指定的文件。

如果只有一个可执行文件，可以简写为：

{
  "name": "create-uver",
  "bin": "./bin/create.js"
}

此时命令名就是 name 字段的值。

5.3 man — 帮助手册

{
  "man": ["./man/doc.1", "./man/doc.2"]
}

指定 man 命令的文档文件路径，文件必须以数字结尾或以 .gz 压缩。

六、依赖管理字段

6.1 dependencies — 生产依赖

{
  "dependencies": {
    "lodash-es": "^4.17.21",
    "vue": "^3.4.0",
    "vue-router": "^4.5.0"
  }
}

项目运行时必须的依赖，npm install 默认安装，最终会被打包进产物中。

6.2 devDependencies — 开发依赖

{
  "devDependencies": {
    "typescript": "^5.3.3",
    "vite": "^6.3.5",
    "eslint": "^9.3.4",
    "prettier": "^3.2.5"
  }
}

仅开发阶段需要的依赖（构建工具、Linter、测试框架等）。其他项目安装你的包时不会安装 devDependencies。

6.3 peerDependencies — 宿主依赖

{
  "peerDependencies": {
    "vue": "^3.0.0",
    "react": "^18.0.0"
  }
}

声明"我需要宿主环境提供这个依赖"，而不是自己安装一份。最经典的场景是 UI 组件库 —— element-plus 声明 peerDependencies: { "vue": "^3.0.0" }，因为它不应该自带一份 Vue。

6.4 peerDependenciesMeta — 宿主依赖元信息

{
  "peerDependencies": {
    "vue": "^3.0.0",
    "react": "^18.0.0"
  },
  "peerDependenciesMeta": {
    "react": {
      "optional": true
    }
  }
}

标记某个 peerDependency 为可选，未安装时不会报警告。

6.5 optionalDependencies — 可选依赖

{
  "optionalDependencies": {
    "fsevents": "^2.3.0"
  }
}

安装失败时不会导致整个 npm install 失败。典型场景：fsevents 仅在 macOS 下可用。

6.6 bundleDependencies / bundledDependencies — 捆绑依赖

{
  "bundleDependencies": ["lodash", "chalk"]
}

npm pack 时会将这些依赖打包进 tarball。适用于需要确保特定版本依赖的场景，或内网环境发布。

6.7 overrides（npm）/ resolutions（yarn）— 依赖覆盖

npm（overrides）：

{
  "overrides": {
    "source-map": "^0.7.4"
  }
}

yarn（resolutions）：

{
  "resolutions": {
    "source-map": "^0.7.4"
  }
}

pnpm（pnpm.overrides）：

{
  "pnpm": {
    "overrides": {
      "source-map": "^0.7.4"
    }
  }
}

强制将依赖树中所有匹配的包替换为指定版本。常用于修复深层依赖的安全漏洞或兼容性问题。

版本号范围速查

七、发布配置字段

7.1 private — 私有包

{
  "private": true
}

设置为 true 后，npm publish 会直接拒绝发布。用于防止 monorepo 根目录或内部项目被意外发布到公共 npm。

7.2 publishConfig — 发布配置

{
  "publishConfig": {
    "registry": "http://jfrog.gdu-tech.com/artifactory/api/npm/gdu-npm-package/",
    "access": "public",
    "tag": "latest"
  }
}

7.3 repository — 仓库信息

{
  "repository": {
    "type": "git",
    "url": "https://github.com/user/project.git",
    "directory": "packages/cloud-sdk"
  }
}

directory 字段在 monorepo 中非常有用，指明包在仓库中的具体位置。

npm 官网会根据此字段在包详情页展示源码链接。

八、环境约束字段

8.1 engines — 运行环境要求

{
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=9.15.0",
    "npm": ">=8.0.0"
  }
}

声明项目所需的 Node.js 和包管理器版本。默认仅作为建议，如需强制校验：

• npm： 在 .npmrc 中设置 engine-strict=true
• yarn： 自动强制检查
• pnpm： 自动强制检查

8.2 os — 操作系统限制

{
  "os": ["darwin", "linux", "!win32"]
}

限制包可运行的操作系统。! 前缀表示排除。

8.3 cpu — CPU 架构限制

{
  "cpu": ["x64", "arm64", "!ia32"]
}

限制包可运行的 CPU 架构。

8.4 packageManager — 指定包管理器

{
  "packageManager": "pnpm@9.15.0"
}

Node.js 16.9+ 引入的 Corepack 特性。声明项目使用的包管理器及精确版本，搭配 corepack enable，其他包管理器会被拦截。

九、Monorepo 相关字段

9.1 workspaces — 工作空间

npm/yarn：

{
  "workspaces": [
    "packages/*",
    "business/*"
  ]
}

pnpm 使用独立的 pnpm-workspace.yaml：

packages:
  - 'packages/*'
  - 'business/*'

工作空间允许在一个仓库中管理多个包，共享 node_modules，实现包之间的互相引用。

9.2 pnpm — pnpm 专有配置

{
  "pnpm": {
    "overrides": {
      "source-map": "^0.7.4"
    },
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*"],
      "allowedVersions": {
        "vue": "3"
      }
    },
    "neverBuiltDependencies": ["fsevents"],
    "patchedDependencies": {
      "express@4.18.2": "patches/express@4.18.2.patch"
    }
  }
}

pnpm 的专属扩展配置项，功能非常丰富：

十、工具链配置字段

许多工具支持直接在 package.json 中配置，免去创建额外配置文件。

10.1 lint-staged

{
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yaml,yml}": ["prettier --write"]
  }
}

配合 husky 在 git commit 前对暂存文件执行 lint 和格式化。

10.2 browserslist

{
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not dead",
    "not ie 11"
  ]
}

声明目标浏览器范围，影响 Babel、PostCSS Autoprefixer、SWC 等工具的编译输出。

10.3 sideEffects

{
  "sideEffects": false
}

告知打包工具（Webpack/Rollup/Vite）该包的所有模块都没有副作用，可以安全 Tree Shaking。

也可以指定有副作用的文件：

{
  "sideEffects": ["*.css", "*.scss", "./src/polyfill.js"]
}

这是优化打包体积最关键的字段之一。如果你的库设置了 "sideEffects": false，使用者只 import 了一个函数，打包工具就敢放心地把其余代码全部删掉。

10.4 config

{
  "config": {
    "port": "8080"
  }
}

可以在 npm scripts 中通过 npm_package_config_port 环境变量读取，用户可以用 npm config set project:port 3000 覆盖。

10.5 其他工具内联配置

以下工具都支持在 package.json 中直接配置：

十一、不常见但有用的字段

11.1 flat — 扁平化依赖（yarn）

{
  "flat": true
}

强制 yarn 安装依赖时使用扁平结构，如果有版本冲突会提示用户选择。

11.2 preferGlobal — 建议全局安装（已废弃）

{
  "preferGlobal": true
}

npm 5+ 已废弃此字段，但部分老项目可能还在使用。

11.3 deprecated — 废弃提示

不是在 package.json 中设置的字段，而是通过 npm deprecate 命令发布：

npm deprecate my-package@"<2.0.0" "请升级到 2.x 版本"

安装时会显示黄色警告。

十二、字段优先级总结

入口文件解析优先级

不同工具对入口字段的解析优先级不同：

Node.js（>=12.11）：

exports > main

Webpack 5：

exports > browser > module > main

Vite / Rollup：

exports > module > main

TypeScript：

exports["."]["types"] > types > typings > main(.d.ts)

一张图看清全貌

package.json
├── 📋 基本信息
│   ├── name            # 包名
│   ├── version         # 版本号
│   ├── description     # 描述
│   ├── keywords        # 关键词
│   ├── license         # 协议
│   ├── author          # 作者
│   └── contributors    # 贡献者
│
├── 📦 入口文件
│   ├── main            # CJS 入口
│   ├── module          # ESM 入口
│   ├── browser         # 浏览器入口
│   ├── types           # TS 类型入口
│   ├── exports         # 条件导出（现代方案）
│   └── type            # 模块系统声明
│
├── 📁 文件管控
│   ├── files           # 发布白名单
│   └── directories     # 目录结构声明
│
├── ⚙️ 脚本与命令
│   ├── scripts         # NPM 脚本
│   ├── bin             # 可执行文件
│   └── man             # 帮助手册
│
├── 📚 依赖管理
│   ├── dependencies          # 生产依赖
│   ├── devDependencies       # 开发依赖
│   ├── peerDependencies      # 宿主依赖
│   ├── peerDependenciesMeta  # 宿主依赖元信息
│   ├── optionalDependencies  # 可选依赖
│   ├── bundleDependencies    # 捆绑依赖
│   └── overrides/resolutions # 依赖覆盖
│
├── 🚀 发布配置
│   ├── private         # 私有标记
│   ├── publishConfig   # 发布配置
│   └── repository      # 仓库信息
│
├── 🔒 环境约束
│   ├── engines         # Node/npm 版本要求
│   ├── os              # 操作系统限制
│   ├── cpu             # CPU 架构限制
│   └── packageManager  # 包管理器声明
│
├── 🏗️ Monorepo
│   ├── workspaces      # 工作空间
│   └── pnpm            # pnpm 专有配置
│
└── 🔧 工具链配置
    ├── lint-staged     # 暂存文件 lint
    ├── browserslist    # 目标浏览器
    ├── sideEffects     # 副作用声明
    └── config          # 自定义配置

十三、最佳实践

1. 库开发的标准 package.json 模板

{
  "name": "@scope/my-lib",
  "version": "1.0.0",
  "description": "A modern library",
  "type": "module",
  "main": "dist/index.cjs",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "files": ["dist"],
  "sideEffects": false,
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
    "lint": "eslint src",
    "test": "vitest"
  },
  "peerDependencies": {
    "vue": "^3.0.0"
  },
  "peerDependenciesMeta": {
    "vue": { "optional": true }
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "publishConfig": {
    "access": "public"
  },
  "license": "MIT"
}

2. Monorepo 根目录模板

{
  "name": "my-monorepo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=18.0.0"
  },
  "scripts": {
    "dev": "pnpm --filter app dev",
    "build": "pnpm -r build",
    "lint": "eslint .",
    "prepare": "husky install"
  },
  "devDependencies": {
    "eslint": "^9.0.0",
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0"
  },
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"]
  }
}

3. 常见误区

结语

package.json 看似简单，实则承载了包的身份信息、入口解析、依赖管理、构建配置、发布流程等方方面面。理解每一个字段的含义和使用场景，不仅能帮你写出更规范的 npm 包，还能在排查 "模块找不到"、"类型丢失"、"打包体积过大" 等问题时快速定位根因。

希望这篇文章能成为你的 package.json 随身手册，收藏备用！

如果觉得有帮助，别忘了点个赞 👍 收藏一下，后续还会更新更多前端工程化干货。

发布时间：2020年6月 ES11 是一个重要版本，新增了空值合并、可选链、BigInt、动态导入等特性。

1. 可选链运算符（Optional Chaining）?.

安全地访问深层嵌套的属性，遇到 null 或 undefined 时短路返回 undefined，不报错。

基本用法

let user = {
  name: '张三',
  address: {
    city: '北京',
    street: '长安街'
  }
};

// 旧写法
let city = user && user.address && user.address.city;

// 新写法
let city = user?.address?.city;     // '北京'
let zip = user?.address?.zip;       // undefined（不会报错）
let phone = user?.contact?.phone;   // undefined

可选链调用方法

let obj = {
  method() { return 42; }
};

obj.method?.();     // 42
obj.otherMethod?.(); // undefined（不会报错）

可选链访问数组元素

let arr = null;
let item = arr?.[0];      // undefined
let item2 = arr?.[0]?.name; // undefined

注意事项

// 可选链不能用于赋值
obj?.name = '李四';   // SyntaxError

// 如果前面的值为 null/undefined，后面的表达式不会执行
let a = null;
let b = a?.foo.bar.baz();  // undefined，foo.bar.baz() 不会执行

实际应用

// 从 API 返回的数据中安全取值
let data = response?.data?.list?.[0]?.name;

// DOM 操作
let value = document.querySelector('#input')?.value;

// React/Vue 中
let userName = this.props?.user?.name ?? '匿名用户';

2. 空值合并运算符（Nullish Coalescing）??

只在值为 null 或 undefined 时使用默认值（|| 会在值为 0、''、false 时也触发）。

基本用法

// || 的问题：0、''、false 都会被当作假值
let count = 0;
console.log(count || 10);    // 10（错误！0 被当成假值）
console.log(count ?? 10);    // 0（正确！只有 null/undefined 才用默认值）

let name = '';
console.log(name || '匿名');  // '匿名'（错误！空字符串被覆盖）
console.log(name ?? '匿名');  // ''（正确！空字符串是有效值）

与 || 的对比

0 ?? 100;          // 0
0 || 100;          // 100

'' ?? 'default';   // ''
'' || 'default';   // 'default'

false ?? true;     // false
false || true;     // true

null ?? 'fallback';  // 'fallback'
null || 'fallback';  // 'fallback'

undefined ?? 'x';    // 'x'
undefined || 'x';    // 'x'

实际应用

// 设置默认值
let port = config.port ?? 3000;
let host = config.host ?? 'localhost';
let debug = config.debug ?? false;

// 与可选链组合使用
let name = user?.profile?.name ?? '匿名用户';
let count = list?.length ?? 0;

注意：不能与 || 和 && 混用

// 语法错误
null ?? 'default' || 'other';  // SyntaxError

// 需要加括号
(null ?? 'default') || 'other';  // 'default'

3. BigInt（大整数）

表示任意精度的整数，突破 Number.MAX_SAFE_INTEGER（2^53 - 1）的限制。

创建 BigInt

// 方式1：数字后加 n
let big1 = 9007199254740993n;

// 方式2：BigInt() 函数
let big2 = BigInt(9007199254740993);
let big3 = BigInt('9007199254740993');

解决精度问题

// Number 的精度限制
9007199254740992 === 9007199254740993;  // true（精度丢失！）

// BigInt 没有精度限制
9007199254740992n !== 9007199254740993n; // true

运算

let a = 12345678901234567890n;
let b = 98765432109876543210n;

a + b;   // 111111111011111111100n
a - b;   // -86419753208641975320n
a * b;   // 1219326311370217952237463801111263526900n
a / b;   // 0n（BigInt 除法向下取整）
a % b;   // 12345678901234567890n

// 比较运算
10n > 5;          // true
10n === 10;       // false（类型不同）
10n == 10;        // true（宽松相等）

注意事项

// BigInt 不能与 Number 混合运算
10n + 5;    // TypeError

// 需要先转换
Number(10n) + 5;  // 15
BigInt(5) + 10n;  // 15n

// 不能用 Math 方法
Math.max(1n, 2n);  // TypeError

// JSON 不支持 BigInt
JSON.stringify({ a: 1n });  // TypeError

4. Promise.allSettled()

等待所有 Promise 完成（无论成功或失败），返回每个 Promise 的结果：

基本用法

let p1 = Promise.resolve('成功1');
let p2 = Promise.reject('失败');
let p3 = Promise.resolve('成功2');

Promise.allSettled([p1, p2, p3]).then(results => {
  results.forEach(result => {
    if (result.status === 'fulfilled') {
      console.log('成功:', result.value);
    } else {
      console.log('失败:', result.reason);
    }
  });
});
// 成功: 成功1
// 失败: 失败
// 成功: 成功2

与 Promise.all 的区别

// Promise.all：任一失败就整体失败
Promise.all([p1, p2, p3])
  .then(res => console.log(res))
  .catch(err => console.log('有失败的:', err));
// 输出：有失败的: 失败

// Promise.allSettled：全部完成后才返回，包含每个结果
Promise.allSettled([p1, p2, p3])
  .then(res => console.log(res));
// [
//   { status: 'fulfilled', value: '成功1' },
//   { status: 'rejected', reason: '失败' },
//   { status: 'fulfilled', value: '成功2' }
// ]

实际应用

// 批量请求，关心所有结果
async function fetchAll(urls) {
  let results = await Promise.allSettled(
    urls.map(url => fetch(url).then(r => r.json()))
  );
  
  let succeeded = results
    .filter(r => r.status === 'fulfilled')
    .map(r => r.value);
  
  let failed = results
    .filter(r => r.status === 'rejected')
    .map(r => r.reason);
  
  console.log(`成功: ${succeeded.length}, 失败: ${failed.length}`);
  return { succeeded, failed };
}

5. 动态导入 import()

运行时按需加载模块，返回 Promise：

基本用法

// 静态导入：编译时加载，必须写在顶部
import { module } from './module.js';

// 动态导入：运行时按需加载
let module = await import('./module.js');

按需加载

// 点击按钮时才加载
button.addEventListener('click', async () => {
  let { Chart } = await import('./chart.js');
  new Chart(canvas, config);
});

条件加载

async function loadPolyfill() {
  if (!window.Promise) {
    await import('promise-polyfill');
  }
}

路由懒加载

// React 路由懒加载
const Home = React.lazy(() => import('./Home'));
const About = React.lazy(() => import('./About'));

注意

• 动态导入返回模块的命名空间对象
• 可以在普通脚本中使用（不限于模块脚本）

6. globalThis

统一的全局对象，在不同环境下指向正确的全局对象：

// 不同环境的全局对象不同：
// 浏览器中：window
// Web Worker 中：self
// Node.js 中：global

// ES11 提供统一的 globalThis
console.log(globalThis);  // 浏览器中指向 window

实际应用

// 兼容写法（旧）
let globalObj = typeof window !== 'undefined' ? window
  : typeof global !== 'undefined' ? global
  : typeof self !== 'undefined' ? self : {};

// ES11 简化
let globalObj = globalThis;

7. String.prototype.matchAll()

返回字符串中所有匹配正则表达式的迭代器：

基本用法

let str = 'test1test2test3';
let matches = str.matchAll(/t(e)(st(\d?))/g);

for (let match of matches) {
  console.log(match);
}
// ['test1', 'e', 'st1', '1', ...]
// ['test2', 'e', 'st2', '2', ...]
// ['test3', 'e', 'st3', '3', ...]

与 match 的区别

// match 带 g 标志时，只返回匹配的字符串
'test1test2'.match(/t(e)st(\d)/g);
// ['test1', 'test2']

// matchAll 返回完整的匹配信息（包括捕获组）
[...'test1test2'.matchAll(/t(e)st(\d)/g)];
// [
//   ['test1', 'e', '1', ...],
//   ['test2', 'e', '2', ...]
// ]

注意

• matchAll 要求正则必须有 g 标志
• 返回的是迭代器，不是数组（可用 ... 或 Array.from() 转换）

8. for...in 标准化枚举顺序

ES11 进一步明确了 for...in 遍历对象字符串键时的顺序：

1. 整数索引形式的键（按数值升序）
2. 其他字符串键（按创建顺序）

注意： for...in 不会遍历 Symbol 键。

let obj = {};
obj[2] = 'b';
obj[0] = 'a';
obj[1] = 'c';
obj['name'] = '张三';
obj['age'] = 18;
obj[Symbol('id')] = 1;

for (let key in obj) {
  console.log(key);
}
// 输出顺序：'0', '1', '2', 'name', 'age'
// Symbol('id') 不会被 for...in 遍历到

总结

本文由云软件体验技术团队郑志超原创。

前言

🌟 情景再现：小明的“职场救赎”

这是小明入职这家大型电商平台公司的第一天。屁股还没坐热，老板就走过来丢下一个紧急任务：“小明，有个大客户叫王五，因为百亿补贴活动，我们需要给他补发一个 1000 元的价保申请单。你赶紧操作一下，客户等着呢。”

小明愣住了。作为刚入职不到两小时的新人，他甚至连后台系统的入口、各级菜单的功能都还没摸清，更别提复杂的价保审核流程和财务对账逻辑了。看着老板匆忙离去的背影，小明坐在工位上对着密密麻麻的业务后台菜单发呆，心里焦虑万分，又不敢在这时候去打扰忙碌的老板请教这种“基础操作”。

这时，坐在旁边的小红看出了小明的窘迫，笑着指了指屏幕右下角的图标：“别愁啦，咱们公司的管理后台集成了 WebMCP + WebSkills 智能系统。你直接跟它说话就行。”

小明半信半疑地打开助手，试着输入了一句：  “帮我给用户王五创建一个价保申请单，金额 1000 元，原因为百亿补贴。”

奇迹发生了！系统立刻自动定位到了用户管理模块，识别了王五的身份，并调取了相关的订单信息。几秒钟后，屏幕上直接弹出了一个预填好的申请单确认框，上面清晰地列出了所有申请细节，并提示：“已为您准备好价保申请单，请确认无误后点击‘提交’。”

小明屏住呼吸，轻轻一点确认按钮，任务圆满完成。

原本以为要折腾一上午的复杂业务，竟然在一句话之间就解决了。这个“神操作”不仅让小明保住了入职第一天的体面，更让他真实感受到了智能化应用带来的效率革命。

以下是模拟小明操作的视频演示（欢迎访问 在线演示地址 亲自体验）：

内容摘要：本文深度解析了 WebMCP + WebSkills 这套专为前端页面驱动设计的“组合拳”方案。通过解决现有自动化方案（无障碍适配、视觉模型）在安全性、成本及适配难度上的核心痛点，提供了 Vue、Angular 及 React 三大主流技术栈的工程级最佳实践，助力开发者在不改变现有业务系统的架构下，实现极简、高效、安全的 AI 驱动页面操作。同时，借助 WebAgent 远程遥控，用户只需手机扫码或输入识别码，即可通过移动端直接遥控桌面页面——这是 WebMCP 在交互体验上的重大突破。

1. 背景与痛点

1.1 场景引子：为什么页面自动化这么难？

做前端工程、AI业务接入的小伙伴，是不是都有过这样的崩溃时刻？想实现页面自动化操作，要么被各种方案的坑绊住脚，要么配置复杂到让人头大，好不容易跑通还面临安全隐患……别慌！这篇文档要介绍的“组合拳”——WebMCP+WebSkills，就是帮你在不大改现有系统的前提下，把页面操作做得又稳又安全。

1.2 业界主流方案与痛点

先吐个槽：业界现有方案，坑是真的多！

在 WebMCP 出现之前，咱们做页面操作自动化，主流就两种方案，但说句实在话，用起来都让人一言难尽，痛点直接拉满：

方案一：基于无障碍信息（如 chrome-devtools-mcp）

听着挺专业，但实际用起来全是“门槛”：首先得要求业务系统页面做好完善的无障碍信息适配，可现实里很多老项目、复杂业务页面，根本达不到这个要求；其次，业务逻辑一旦复杂，基于无障碍信息的操作就会出现各种不确定性，时而正常时而报错，排查起来比找 bug 还难；更麻烦的是，想用它还得额外装浏览器扩展插件，或者依赖 playwright 等工具，步骤繁琐，兼容性还参齐不齐。

方案二：基于视觉模型截图操作

这个方案看似不用适配页面，实则“费钱又费时间”：视觉模型运行起来特别消耗 token，长期用下来成本蹭蹭涨；而且执行速度慢得让人着急，复杂业务操作能卡到你怀疑人生；最关键的是，它根本扛不住复杂业务系统的考验，稍微多几个交互步骤就直接“罢工”。

共同致命伤：安全不可控

不管是无障碍信息方案，还是视觉模型方案，都存在一个核心隐患——安全性。两种方案都需要一定程度上获取页面敏感信息，且缺乏有效的安全管控机制，一不小心就可能造成数据泄露，给业务带来不可挽回的损失。

1.3 WebMCP + WebSkills 的定位

就在大家被这些痛点折磨得焦头烂额时，WebMCP+WebSkills 横空出世，直接精准戳中所有痛点，给前端页面操作自动化带来了新希望！

WebMCP 不是“替代者”，而是“最强补充”

很多小伙伴会误以为 WebMCP 是要取代业界现有的 MCP 协议，其实不然！WebMCP 是基于业界 MCP 协议打造的前端优化方案，核心定位是“补充和增强”——它保留了 MCP 协议的核心优势，同时针对前端页面操作的痛点做了针对性优化，让页面操作更简单、更高效、更安全。

WebSkills：让 AI 真的“懂你的业务”

而 WebSkills 则是 WebMCP 的“神助攻”，它能进一步增强 AI 对业务的理解能力，让页面操作自动化更智能，哪怕是复杂的业务场景，也能轻松应对，两者搭配使用，直接实现“1+1>2”的效果。

WebAgent 远程遥控：移动端直接操控桌面页面

WebMCP + WebSkills 还有一个杀手级亮点——远程遥控。通过 useWebAgentServer 将本地 MCP Server 桥接到远端 Agent 平台，用户扫描二维码或输入 6 位识别码，即可在手机上通过自然语言指令遥控桌面浏览器页面。真正实现"移动端说一句话，桌面页面帮你干活"。

2. 三大技术栈最佳实践总览

干货来袭：三大技术栈最佳实践，直接抄作业！

不管你是用 Vue、React 还是 Angular，WebMCP+WebSkills 都能完美适配，而且实现方式高度统一：核心是通过前端路由 + 页面工具（Page Tool Bridge）把业务页面和 MCP 工具打通，再通过 WebSkills 和 TinyRemoter 做“知识与对话入口”  。下面分别给出 Vue / Angular 的摘要示例，并附上工程级最佳实践链接。

2.1 Vue 工程最佳实践（摘要）

源码工程：packages/doc-ai
完整工程路径：packages/doc-ai
详细文档：docs/guide/vue-webmcp-best-practice.md

步骤 1：安装依赖

pnpm add @opentiny/next-sdk @opentiny/next-remoter

说明：这里直接引入 WebMCP 核心 SDK 与 TinyRemoter 组件包，为后续“页面工具 + 对话框 UI”打基础。

步骤 2：在 main.ts 中注册路由导航器

// src/main.ts
import { createApp } from 'vue'
import router from './router'
import App from './App.vue'
import { setNavigator } from '@opentiny/next-sdk'

const app = createApp(App)
app.use(router)
app.mount('#app')

// 告诉 SDK：需要跳转页面时统一走 router.push
setNavigator((route) => router.push(route))

中文小结：setNavigator 是 Page Tool Bridge 的前提，只需在入口调用一次，之后所有“与页面绑定的工具”在执行时都会通过这里完成路由跳转。

步骤 3：配置业务路由

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: () => import('../views/home/index.vue') },
    { path: '/product-list', component: () => import('../views/product-list/index.vue') },
    { path: '/price-protection', component: () => import('../views/price-protection/index.vue') }
  ]
})

export default router

中文小结：后面在 registerTool 和 registerPageTool 里会引用这些 path，请保持一致，避免因为路由不对导致工具调用超时。

步骤 4：创建 MCP Server，并通过 withPageTools 绑定路由

// src/mcp-servers/index.ts
import {
  WebMcpServer,
  createMessageChannelPairTransport,
  withPageTools,
  registerNavigateTool
} from '@opentiny/next-sdk'
import registerProductGuideTools from './product-guide/tools'
import registerPriceProtectionTools from './price-protection/tools'

const rawServer = new WebMcpServer()
const [serverTransport, clientTransport] = createMessageChannelPairTransport()

export const server = withPageTools(rawServer)
export { clientTransport }

export const createMcpServer = async () => {
  registerNavigateTool(rawServer)
  registerProductGuideTools(server)
  registerPriceProtectionTools(server)
  await rawServer.connect(serverTransport)
}

中文小结：withPageTools 让工具可以和路由产生映射；registerNavigateTool 注册了一个通用的 navigate_to_page 工具，供大模型主动发起“先跳转再用页面工具”的链路。

步骤 5：注册与页面绑定的业务工具

// src/mcp-servers/product-guide/tools.ts
import { z } from '@opentiny/next-sdk'
import type { PageAwareServer } from '@opentiny/next-sdk'

const registerProductGuideTools = (server: PageAwareServer) => {
  server.registerTool(
    'product-guide',
    {
      title: '产品指南',
      description: '根据产品 ID 获取产品详细信息',
      inputSchema: {
        productId: z.string().describe('产品 ID')
      }
    },
    { route: '/product-list' } // 工具执行时自动导航到该路由
  )
}

export default registerProductGuideTools

中文小结：第三个参数 { route: '/product-list' } 是关键，它告诉 SDK“这个工具需要在哪个页面内执行”，从而触发 Page Tool Bridge 的自动跳转与消息投递。

步骤 6：在页面内通过 registerPageTool 注册工具处理器

<!-- src/views/product-list/index.vue -->
<template>
  <div class="products-page">
    <div v-for="product in products" :key="product.id">{{ product.name }} - ¥{{ product.price }}</div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { registerPageTool } from '@opentiny/next-sdk'
import productsData from './products.json'

type Product = {
  id: number
  name: string
  price: number
  stock: number
  status: 'on' | 'off' | string
}

const products = ref<Product[]>(productsData as Product[])
let cleanupPageTool: () => void

onMounted(() => {
  cleanupPageTool = registerPageTool({
    handlers: {
      'product-guide': async ({ productId }: { productId: string }) => {
        const product = products.value.find((p) => String(p.id) === productId)
        const text = product ? `产品信息：${JSON.stringify(product, null, 2)}` : `未找到产品 ID 为 ${productId} 的商品`
        return { content: [{ type: 'text', text }] }
      }
    }
  })
})

onUnmounted(() => cleanupPageTool?.())
</script>

中文小结：页面挂载时把 handler 注册进去，卸载时清理；handler 中可以直接访问 Vue 响应式数据，实现“AI 调工具 → 工具调页面逻辑”的完整闭环。

步骤 7：在 App.vue 中挂载 TinyRemoter + Skills，并接入远程遥控（可选）

<!-- src/App.vue -->
<template>
  <div class="app-container">
    <router-view />
    <TinyRemoter
      :show="true"
      :skills="skillMdModules"
      :mcpServers="mcpServers"
      :menuItems="menuItems"
      title="智能助手"
      :llmConfig="llmConfig"
    />
  </div>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { TinyRemoter } from '@opentiny/next-remoter'
import { createMcpServer, clientTransport } from './mcp-servers'
import { useWebAgentServer } from './mcp-servers/useWebAgentServer'

const llmConfig = {
  apiKey: import.meta.env.VITE_LLM_API_KEY || 'your-api-key-placeholder',
  baseURL: import.meta.env.VITE_LLM_BASE_URL || 'https://api.openai.com/v1',
  providerType: 'openai',
  model: 'gpt-4o',
  maxSteps: 10
}

const skillMdModules = import.meta.glob('./skills/**/*', {
  query: '?raw',
  import: 'default',
  eager: true
}) as Record<string, string>

const mcpServers = {
  'my-mcp-server': {
    type: 'local' as const,
    transport: clientTransport
  }
}

const menuItems = ref<any[]>([])

onMounted(async () => {
  // 本地 MCP 核心功能：失败直接抛出
  await createMcpServer()

  // 远程遥控增强功能：失败只打印警告，不影响本地对话
  try {
    const result = await useWebAgentServer()
    if (result?.sessionId) {
      const remoteUrl = `https://agent.opentiny.design/mcp?sessionId=${result.sessionId}`
      menuItems.value = [
        { action: 'remote-url', text: '遥控器链接', desc: remoteUrl, tip: remoteUrl, active: true, showCopyIcon: true },
        { action: 'remote-control', text: '识别码', desc: result.sessionId.slice(-6), know: true, showCopyIcon: true }
      ]
    }
  } catch (err) {
    console.warn('[WebAgent] 远程遥控初始化失败，本地功能不受影响：', err)
  }
})
</script>

中文小结：menuItems 在 WebAgent 连接成功后填充，TinyRemoter 会自动在悬浮菜单中显示"遥控器链接"和"识别码"。本地 MCP 与远程遥控必须分开 try/catch 处理，避免网络问题导致本地对话功能也一起失效。详细接入方式见 远程遥控亮点章节。

2.2 Angular 工程最佳实践（摘要）

源码工程：packages/doc-ai-angular
完整工程路径：packages/doc-ai-angular
详细文档：docs/guide/angular-webmcp-best-practice.md

Angular 与 Vue 最大的差异在于：TinyRemoter 是 Vue 组件，Angular 不能直接引入，需要通过 iframe + MessageChannel 与主应用通讯。

整体架构：

• • Angular 主应用：负责路由、业务页面、WebMCP Server、registerPageTool
• • Vue Remoter 子应用（iframe 内）：负责 TinyRemoter UI + Skills，使用 createMessageChannelClientTransport 连接主应用

步骤 1：在根组件中注册 setNavigator 并启动 MCP Server

// src/app/app.component.ts
import { Component, OnInit, inject } from '@angular/core'
import { Router, RouterOutlet } from '@angular/router'
import { setNavigator } from '@opentiny/next-sdk'
import { createMcpServer } from '../mcp-servers'

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent implements OnInit {
  private router = inject(Router)

  async ngOnInit(): Promise<void> {
    setNavigator(async (route) => {
      const navigated = await this.router.navigateByUrl(route)
      if (!navigated) {
        throw new Error(`页面跳转失败：导航至 "${route}" 被取消或拦截`)
      }
    })

    await createMcpServer()
  }
}

中文小结：和 Vue 版类似，这里统一封装“页面跳转策略”，同时在应用入口启动 MCP Server，确保后续 iframe 连接时已有可用的工具服务。

步骤 2：在根模板中通过 iframe 嵌入 Remoter

<!-- src/app/app.component.html -->
<div class="app-container">
  <div class="main-content">
    <router-outlet />
  </div>
  <aside class="remoter-sidebar">
    <iframe class="remoter-frame" src="/remoter.html" frameborder="0" allow="clipboard-write" title="AI 助手"></iframe>
  </aside>
</div>

中文小结：/remoter.html 会通过代理指向 Remoter 子应用入口（例如 Vite dev server 的 /remoter/），两端同源后即可使用 MessageChannel 互通。

步骤 3：在主窗口创建 MCP Server，并暴露 MessageChannel 服务端

// src/mcp-servers/index.ts
import {
  WebMcpServer,
  createMessageChannelServerTransport,
  withPageTools,
  registerNavigateTool
} from '@opentiny/next-sdk'
import registerProductGuideTools from './product-guide/tools'
import registerPriceProtectionTools from './price-protection/tools'

const rawServer = new WebMcpServer()
export const server = withPageTools(rawServer)

export const createMcpServer = async () => {
  registerNavigateTool(rawServer)
  registerProductGuideTools(server)
  registerPriceProtectionTools(server)

  const serverTransport = createMessageChannelServerTransport('local-mcp')
  await serverTransport.listen()
  await rawServer.connect(serverTransport)
}

中文小结：这里不再使用“同窗口内存对”的 createMessageChannelPairTransport，而是用 createMessageChannelServerTransport('local-mcp') 等待 iframe 侧主动连入。

步骤 4：在 Angular 页面中注册页面工具处理器

// src/app/pages/comprehensive/comprehensive.component.ts（节选）
import { Component, OnInit, OnDestroy } from '@angular/core'
import { registerPageTool } from '@opentiny/next-sdk'

@Component({
  /* 模板与样式省略 */
})
export class ComprehensiveComponent implements OnInit, OnDestroy {
  products: Product[] = productsData as Product[]
  private cleanupPageTool!: () => void

  ngOnInit(): void {
    this.cleanupPageTool = registerPageTool({
      handlers: {
        'product-guide': async ({ productId }: { productId: string }) => {
          const product = this.products.find((p) => String(p.id) === productId)
          const text = product
            ? `产品信息：${JSON.stringify(product, null, 2)}`
            : `未找到产品 ID 为 ${productId} 的商品`
          return { content: [{ type: 'text', text }] }
        }
      }
    })
  }

  ngOnDestroy(): void {
    this.cleanupPageTool?.()
  }
}

中文小结：写法和 Vue 版高度类似，只是生命周期钩子由 onMounted/onUnmounted 换成了 ngOnInit/ngOnDestroy，其余 Page Tool Bridge 行为完全一致。

步骤 5：在 Remoter 子应用中，通过 createMessageChannelClientTransport 连接主窗口

<!-- remoter/src/App.vue（节选） -->
<template>
  <tiny-remoter :skills="skillMdModules" :show="true" :fullscreen="true" :mcpServers="mcpServers" />
</template>

<script setup lang="ts">
import { TinyRemoter } from '@opentiny/next-remoter'
import { createMessageChannelClientTransport } from '@opentiny/next-sdk'

const skillMdModules = import.meta.glob('./skills/**/*', {
  query: '?raw',
  import: 'default',
  eager: true
}) as Record<string, string>

const clientTransport = createMessageChannelClientTransport('local-mcp', window.parent)

const mcpServers = {
  'local-mcp-server': {
    type: 'local',
    transport: clientTransport
  }
}
</script>

中文小结：endpoint 'local-mcp' 和主窗口必须一致，通过这一对 Transport，TinyRemoter 就可以把所有工具调用发送到 Angular 主应用，再由 Page Tool Bridge 转发到具体页面。

2.3 React 工程最佳实践（工程入口）

源码工程：packages/doc-ai-react
完整工程路径：packages/doc-ai-react

React 工程的整体架构与 Angular 工程高度一致，同样是：

•  主应用（React SPA）  ：直接对接 @opentiny/next-sdk，在浏览器中创建 WebMCP Server、注册业务工具，结合路由和 registerPageTool 在各业务页面内挂载页面工具处理器；
•  Remoter 子应用（Vue）  ：作为一个独立的前端子工程，通过 iframe 嵌入到 React 主应用中，内部渲染 TinyRemoter 组件并加载 WebSkills 文档；
•  通信方式：主应用和 iframe 之间通过 MessageChannel 建立连接，主应用侧暴露服务端 Transport，Remoter 侧创建客户端 Transport，最终由 TinyRemoter 将对话中的工具调用透传到 React 主应用，再由 Page Tool Bridge 负责路由跳转和页面内业务逻辑执行。

简单理解：React 主应用负责“工具和页面”，Remoter 子应用负责“对话 UI 和技能文档”，两者通过 iframe + MessageChannel 打通，整体模式与 Angular 版本完全一致。示例工程可参考 packages/doc-ai-react，根据你的 React 路由和对话组件做适配即可。

2.4 远程遥控：跨设备遥控桌面的杀手级亮点 🎮

这是 WebMCP 区别于所有现有方案的独家能力：无需任何额外硬件或客户端，用手机扫一扫，就能用自然语言遥控桌面浏览器上的业务系统。

原理一句话

桌面浏览器（WebMCP Server）
    ↕ WebSocket 长连接
远端 Agent 平台（sessionId 路由）
    ↕
手机浏览器（遥控端 UI）
    ↓ 用户语音/文字指令
AI 解析意图 → 调用 MCP 工具 → 桌面页面执行 → 结果回显到手机

本地 MCP Server 通过 useWebAgentServer 向远端 Agent 平台注册，获得唯一 sessionId。手机端打开遥控页面并输入识别码（sessionId 后 6 位）或扫描二维码，即与桌面建立会话。

核心 API：useWebAgentServer

// src/mcp-servers/useWebAgentServer.ts
import { WebMcpServer, WebMcpClient, createMessageChannelPairTransport, withPageTools } from '@opentiny/next-sdk'
import { registerAllTools } from './common'

const rawServer = new WebMcpServer()
const client = new WebMcpClient()
const [serverTransport, clientTransport] = createMessageChannelPairTransport()
export const server = withPageTools(rawServer)

const SESSION_ID_KEY = 'web-agent-session-id'

export const useWebAgentServer = async () => {
  registerAllTools(server)
  await rawServer.connect(serverTransport)
  await client.connect(clientTransport)

  const cachedSessionId = localStorage.getItem(SESSION_ID_KEY) ?? undefined
  const { sessionId } = await client.connect({
    sessionId: cachedSessionId,
    agent: true,
    url: 'https://agent.opentiny.design/api/v1/webmcp-trial/mcp'
  })

  if (sessionId) localStorage.setItem(SESSION_ID_KEY, sessionId)
  return { sessionId }
}

三步快速接入

① 创建 useWebAgentServer.ts（如上）

② 在 onMounted 中分离调用（错误隔离是关键！）

onMounted(async () => {
  await createMcpServer() // 本地 MCP：失败直接抛出（核心功能）

  try {
    const result = await useWebAgentServer() // 远程遥控：失败只警告（增强功能）
    if (result?.sessionId) {
      const remoteUrl = `https://agent.opentiny.design/mcp?sessionId=${result.sessionId}`
      menuItems.value = [
        { action: 'remote-url', text: '遥控器链接', desc: remoteUrl, tip: remoteUrl, active: true, showCopyIcon: true },
        { action: 'remote-control', text: '识别码', desc: result.sessionId.slice(-6), know: true, showCopyIcon: true }
      ]
    }
  } catch (err) {
    console.warn('[WebAgent] 远程遥控初始化失败，不影响本地功能：', err)
  }
})