ArenaPro Creator

Appearance

进阶指南：安全地使用外部 NPM 包 ​

你想在项目中使用一个开源的状态管理库 (如 zustand)，或者一个强大的日期处理工具 (如 dayjs)。你打开终端，熟练地准备敲下 npm install。

但是，你应该问自己一个关键问题：“这个包能在 ArenaPro 里运行吗？”

答案是 “也许” 。这篇指南将教你如何做出明智的、安全的选择，让你能自信地利用 NPM 的强大生态，同时避免那些会导致你项目崩溃的“陷阱”。

黄金法则：兼容性高于一切 ​

在你安装任何 NPM 包之前，必须理解这条黄金法则：并非所有 NPM 包都能在 ArenaPro 环境中运行。

ArenaPro 的脚本运行环境是一个独特的沙箱，它既不是标准的 Node.js，也不是标准的浏览器。如果一个 NPM 包依赖了特定于 Node.js 或浏览器的 API，它就会在 ArenaPro 中运行失败。

一个 NPM 包会不兼容，通常有两个原因：

  1. 依赖了 Node.js 专属 API: 包内部使用了 require('fs') (文件系统), require('http') (网络服务), require('path') 等 Node.js 后端模块。
  2. 依赖了浏览器专属 API: 包内部使用了 document, window, localStorage 等浏览器 DOM 和全局对象。

什么样的包最有可能兼容？

  • 纯粹的算法/工具库：比如数学计算、数据结构、函数式编程工具 (如 Lodash)。
  • 无依赖或依赖很少的库：在 NPM 官网上，它的 "Dependencies" 列表为空或数量很少。
  • 明确标记为 "Isomorphic" / "Universal" 的库：这通常意味着作者已经特意将其设计为可在任何 JavaScript 环境中运行。

实战演练：安装并使用 lodash-es ​

lodash-es 是传奇工具库 lodash 的 ES Module 版本，它完全由纯粹的、不依赖任何环境的工具函数组成。

第 1 步：安装包 ​

打开终端，运行以下命令：

bash
npm install lodash-es

同时，为了让 TypeScript 能够理解 Lodash 的类型，我们还需要安装它的类型定义文件（作为开发依赖）：

bash
npm install @types/lodash-es --save-dev

第 2 步：在代码中导入和使用 ​

现在，你可以在代码中像使用任何本地模块一样，导入 lodash-es 提供的函数。

示例：使用 clamp 和 debounce

ts
// client/src/inputManager.ts

// 从 lodash-es 中导入需要的函数
import { clamp, debounce } from "lodash-es";

// 1. 使用 clamp 函数确保血量不会超过或低于预设范围
function applyDamage(player, amount) {
  const currentHealth = player.getData("health");
  const newHealth = currentHealth - amount;
  // clamp(数字, 最小值, 最大值)
  player.setData("health", clamp(newHealth, 0, 100));
}

// 2. 使用 debounce (防抖) 函数来防止玩家过于频繁地触发某个技能
function onPlayerUseSkill() {
  console.log("技能已施放！进入冷却...");
  // 实际的技能逻辑
}

// 创建一个防抖版本的函数，它在最后一次调用后的 2 秒才会真正执行
// 完美适用于处理技能冷却、防止用户连点等场景
const debouncedSkillHandler = debounce(onPlayerUseSkill, 2000, {
  leading: true, // 第一次点击立即执行
  trailing: false, // 结束后不再执行
});

// 在事件监听中，使用我们防抖后的处理函数
// player.onKey('Q', debouncedSkillHandler);

lodash-es 提供了上百个类似这样好用的工具函数，能极大地简化你的代码。

Checklist：如何审查一个包的兼容性？ ​

在你 npm install 一个新包之前，花两分钟做一个快速的“安全审查”：

  1. 访问 npmjs.com：搜索你要的包。
  2. 查看依赖 (Dependencies)：在包的页面右侧，查看依赖列表。依赖越少、越“纯粹”，兼容的几率就越大。
  3. 寻找关键词：在它的 README 中用 Ctrl+F 搜索 "isomorphic", "universal", "zero dependency", "browser support" 等字眼。
  4. 浏览代码 (抽查)：点击“Repository”链接跳转到它的 GitHub 仓库。随机打开几个 src 目录下的文件，用 Ctrl+F 搜索一下 require('fs') 或 window. 等关键词。如果能搜到，那它很可能不兼容。
  5. 检查 package.json：在 GitHub 仓库中找到 package.json 文件。如果里面同时存在 "main" 和 "browser" 字段，这是一个非常强的信号，说明作者已经考虑到了跨环境兼容性。

官方保障：@dao3fun 命名空间 ​

为了方便开发者，ArenaPro 官方也提供了一系列 NPM 包，它们都发布在 @dao3fun 这个命名空间下 (例如 @dao3fun/arena-rich)。

所有 @dao3fun 下的包，都经过了测试和优化，100% 保证与 ArenaPro 环境兼容。

当你需要实现某个功能时（比如富文本、UI 组件等），我们推荐你优先在 @dao3fun 中寻找有没有现成的解决方案，这比你自己从社区中寻找和测试第三方包要安全和高效得多。

上一篇：自定义构建流程 (Webpack)

下一篇：创建本地共享包 (Monorepo)