> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ku/create-libraries.md).

# 创建库

创建你自己的 Decentraland 库，与他人分享

库是分享常见问题解决方案的绝佳方式。复杂的挑战只需处理一次，把解决方案封装到一个库中，每当再次遇到时，你只需要写一行代码。通过与社区共享库，我们可以让所有创作者的生产力指数级增长。

目前，这些库在 [示例页面](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) 中都可供所有人使用。我们也鼓励你创建并分享自己的库。

按照这里详细说明的步骤，你可以避开创建一个与 Decentraland 场景兼容且易于与他人共享的库时所带来的大部分复杂性。

## 创建一个库

> **📔 注意**: 在构建库之前，请确保你使用的是 Node 20 或更新版本。

要创建你自己的库并通过 NPM 共享，请按以下步骤操作：

1. 新建一个空文件夹，并在其中打开一个新的 Visual Studio Code 窗口。
2. 在 Visual Studio 左侧边栏中选择 Decentraland 选项卡
3. 点击 **创建项目**，然后选择 **库**

   这将为一个 Decentraland 库创建所有默认文件和依赖项。
4. 设置一个唯一的 `name` 在 `package.json`。这是发布到 NPM 时使用的名称，请确保 npm 上没有其他现有项目使用该名称。还要填写描述和任何标签，帮助其他人找到你的库。
5. 创建一个新的 *公开的* GitHub 仓库用于你的项目。

   该项目配置为使用 GitHub Actions，在每次推送到 `main`.

   在 `package.json` 文件中，请确保在 `仓库` 中将 `url` 字段指向你仓库的 URL。这样在浏览 [npmjs.com](https://www.npmjs.com).
6. 获取一个 NPM 令牌：
   1. 在 <https://www.npmjs.com/> 上创建一个账户或登录。
   2. 前往 **账户 > 访问令牌 > 生成新令牌** 创建一个新令牌，赋予它 **发布** 权限。

      成功消息中包含一个新生成令牌的字符串。复制这段字符串并将其保存在安全的地方。
7. 在你的 GitHub 仓库中，前往 **设置 > 密钥 > Actions**，然后点击 **新建仓库密钥**.

   将你的密钥命名为 **NPM\_TOKEN**，并将 NPM 令牌中的字符串粘贴为其值。
8. 向 GitHub 仓库的 main 分支推送一次更改（任意更改）后，软件包就会被发布。

   就这样，现在任何人都可以使用以下方式安装该软件包 `npm i <package-name>`！现在你可以在 [npmjs.com](https://www.npmjs.com).
9. 充实 `/src` 你项目的文件夹，加入你想要公开的所有功能，并将更改推送到 GitHub。

## 开发

将你想要公开的任何函数、组件等添加到库的 `index.ts` 文件中，这样它们就很容易导入。

例如，如果你添加了一个 `RotatorComponent` 字段设为 `index.ts`，那么你可以通过编写以下内容将此组件导入到场景中：

`import { RotatorComponent } from 'my-library'`

在开发库时，通过在新的 Decentraland 场景中使用它来测试你的库。运行以下命令将你的 npm 软件包安装到场景中 `npm i <package-name>`。然后搭建一个用于试用库功能的场景。尝试用你的场景覆盖不同的测试用例，以确保你的库在每种情况下都能按预期工作。

### 快速迭代

如果你需要持续对库做小调整并进行测试，每次都要提交更改，然后等待 npm 发布完成才能在场景中试用新版本，这会让人筋疲力尽。幸运的是，运行库测试有一个快得多的替代方案。

在一个 **测试场景项目**:

1. 将此脚本添加到 `scripts` 列表中，位于 package.json： `"link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"`
2. 运行 `npm install`
3. 运行 `npm install YOUR_LIBRARY_PATH`，例如： `npm install /User/projects/dcl-sdk7-library-test`
4. 运行 `npm run link-sdk`

在 **库项目**:

1. 运行 `npm install`
2. 运行 `npm run build`
3. 运行： `npm link @dcl/sdk @dcl/js-runtime`

> **❗警告**：这些步骤的顺序很重要。换成其他顺序可能无法工作。

这会让你的场景与本地磁盘上库的版本保持同步。对于你想测试的任何库更改，只需在库文件夹上运行 `npm run build` ，无需将更改发布到 GitHub 或 NPM。

> **💡 提示**：要验证链接是否成功，请运行 `npm ls --link`。你应该会看到库名称指向你本地文件中的文件夹。

如果你对库做了更改，你必须运行 `npm run build` 来更新它们。为了避免每次都这样做：

1. 将脚本 "start": "tsc -p tsconfig.json --watch" 添加到库的
2. 运行 `npm start` 在库中运行

当你完成测试后，记得解除库的链接。

1. 在场景文件夹中运行 `npm install <库名称>`
2. 然后在库中运行 `rm -rf node_modules && npm install`

## 版本管理

你的库版本会自动发布到 `npm` 搭配一个 `@latest` 以及一个 `@next` 标签。

该 `@next` 标签始终指向 `main` 分支上的最后一次提交。这个版本可能不稳定，因为最新的更改可能尚未经过测试。你的库用户可以通过执行以下命令安装它（风险自担） `npm i <库名称>@next`.

该 `@latest` 标签指向该库最后一个稳定版本。这通常是你的库用户应该正常安装的版本。npm 在他们执行以下命令时获取的就是这个版本 `npm i <库名称>`.

要让 `@latest` 标签指向你最新的提交，你需要在 GitHub 上进行一次 **发布** 你的库。

1. 打开你项目的 GitHub 页面。打开 **发布** 链接，位于页面右侧边栏。
2. 点击 **创建新的发布草稿**.
3. 开启 **选择标签** 为你的新版本写一个名称，例如 "1.1.0"。也在 **发布标题**上写一个名称。这通常与前者相同，都是 "1.1.0"。

   > 重要：标签必须是数字，不能包含其他字母或符号。这个数字必须高于之前发布的版本。
4. 描述你的发布内容，让用户知道有哪些新内容。

   > 提示：点击按钮 **自动生成发布说明** 以列出自上次发布以来的所有提交。
5. 点击 **发布版本**。此操作会触发一次使用 `@latest` 标签自动发布到 npm 的新版本。你的库用户现在将下载此版本。

## 关于可用性的说明

尽你所能让你的库易于其他创作者使用。我们的假设总会帮助塑造我们所制作的工具。很多时候，这些假设在我们看来是显而易见的，但处于不同背景的其他人可能会有完全不同的假设。

* 为库中的一切谨慎选择名称，包括函数、组件和参数。拥有一个长但自解释的名称，总比一个简短却让人完全摸不着头脑的名称要好。
* 要广泛思考你的库可能的不同使用场景。也许有人会在智能穿戴设备中使用你的库，也许有人需要在某些时候打开或关闭你的系统，也许有人需要在同一个场景中添加你系统的多个实例。并不是每个人都面临与你相同的挑战。
* 话虽如此，你不需要支持所有可能的使用场景。实际上，在灵活性与易用性之间总是需要权衡，打造好工具的关键就在于找到正确的平衡。对于你选择不支持的内容，要策略性地划定边界。不过，清楚地记录你所做出的限制非常重要。
* 这就引出了文档。请清晰地记录你的库，包含示例、每个参数作用的说明、哪些场景无法工作以及你对其使用上下文所做的假设说明。库的 README.md 通常是展示这些内容的最佳位置。
* 另一个很好的方法是直接在代码中添加元数据注释。当用户使用你的库输入时，这些注释会由 IDE（如 VS Studio Code）显示出来。你可以描述每个函数/组件的用途，描述每个参数期望接收什么，以及函数返回什么。得益于此，你的库用户不需要在代码和文档之间切换，一切都在一个地方！例如，看看来自 `@dcl/ecs-scene-utils` 库的这个函数：

  ```ts
  /**
   * 将一个值限制在不超过最小值或最大值。
   *
   * @param value - 输入数字
   * @param min - 最小输出值。
   * @param max - 最大输出值。
   * @returns 位于最小值和最大值之间的映射结果值
   * @public
   */
  export function clamp(value: number, min: number, max: number) {
  	let result = value

  	if (value > max) {
  		result = max
  	} else if (value < min) {
  		result = min
  	}
  	return result
  }
  ```

  该库的用户在输入 `clamp()` 函数：
* 始终声明类型。不要让人猜测他们需要处理什么对象结构。
* 保持你的库轻量，并专注于一个功能。当 Decentraland 场景被编译时，其所有库中的所有代码都会与之一起打包，即使是场景从未调用的代码也是如此。因此，最好避免创建大型臃肿的库。更好的做法是制作精简的库，让创作者只使用他们真正需要的内容。
* 留意你的库仓库，人们可能会提交拉取请求或报告问题。
* 在你的仓库中包含许可信息，这样其他人就知道他们是否可以免费使用你的库。默认库包含一个开放的 Apache 2 许可证，如果你愿意，可以随意更改。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ku/create-libraries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.