# @dcl/asset-packs 中文文档 规范地址：https://npmcn.com/package/%40dcl/asset-packs/ 版本：2\.26\.1 npm 元数据更新时间：2026-11-09T17:04:48.385Z 中文译文更新时间：2026-11-11T17:29:39.760Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dcl/asset-packs 原文对照：https://npmcn.com/package/%40dcl/asset-packs/?lang=original 项目主页：https://github.com/decentraland/creator-hub/tree/main/packages/asset-packs#readme 源码仓库：https://github.com/decentraland/creator-hub ## 关键信息（来自 npm 元数据） - 包体积（解压后）：19.5 MB，169 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：@dcl/ecs ^7\.15\.2 - 首次发布：2023-09-05T21:45:48.343Z - 最新版本发布：2026-11-09T17:04:48.008Z - 近 30 天下载量：11908（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：293（近 12 个月 68 个） ## 中文简介 分散式资产包 -- -- 为分散式场景收集3D资产 ## 安装 ```sh npm install @dcl/asset-packs ``` 也可以使用：`pnpm add @dcl/asset-packs`、`yarn add @dcl/asset-packs`、`bun add @dcl/asset-packs` ## README # 资产包 [![npm version](https://img.shields.io/npm/v/@dcl/asset-packs.svg)](https://www.npmjs.com/package/@dcl/asset-packs) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) [![CI Status](https://github.com/decentraland/creator-hub/workflows/Asset%20Packs/badge.svg)](https://github.com/decentraland/creator-hub/actions/workflows/asset-packs.yml) ## 目录 - [概览](https://npmcn.com/package/%40dcl/asset-packs/#readme-overview) - [快速启动](https://npmcn.com/package/%40dcl/asset-packs/#readme-quick-start) - [使用您的场景中的资产包](https://npmcn.com/package/%40dcl/asset-packs/#readme-using-asset-packs-in-your-scene) - [发展的先决条件](https://npmcn.com/package/%40dcl/asset-packs/#readme-prerequisites-for-development) - [分发](https://npmcn.com/package/%40dcl/asset-packs/#readme-distribution) - [生产](https://npmcn.com/package/%40dcl/asset-packs/#readme-production) - [发展](https://npmcn.com/package/%40dcl/asset-packs/#readme-development) - [部署](https://npmcn.com/package/%40dcl/asset-packs/#readme-deployment) - [地方发展](https://npmcn.com/package/%40dcl/asset-packs/#readme-local-development) - [解决问题](https://npmcn.com/package/%40dcl/asset-packs/#readme-troubleshooting) - [相关的结构决定](https://npmcn.com/package/%40dcl/asset-packs/#readme-related-architecture-decisions) ## 概览 资产储存库是Decentrand生态系统的一个基本组成部分,是默认物品和资产的中央储存和分配系统。 它管理和分发: - **资产包**: 3D 资产按主题( cyberpunk, s蒸汽punk, 起源地城市) 排列的解析集合 - **静态项目**: 有纹理和材料的基本三维模型 - **智能项目**: 具有可编程行为和配置的交互式项目 部署后,所有资产被散开并上载到下面的一桶S3 `contents/:hash`Npm 软件包 `@dcl/asset-packs` 现发布内容包括: - A 类 `catalog.json` 拥有所有资产包的数据和内容散列 - A 类 `bin/index.js` 智能项目功能所需的运行时间 资产可通过 `builder-items.decentraland.*` 通过Cloudflare. ## 快速启动 ### 使用您的场景中的资产包 在您的 Decentrand SDK7 场景中安装软件包 : ```bash npm install @dcl/asset-packs ``` 在您的场景中导入并使用资产包 : ```typescript import { readGltfLocator } from '@dcl/asset-packs' // Use an asset from the catalog const assetId = 'some-asset-id' const gltfSrc = readGltfLocator(assetId) // Use in your scene engine.addEntity({ transform: Transform.create(), gltfContainer: GltfContainer.create({ src: gltfSrc }) }) ``` ### 发展的先决条件 - **节点.js** 22.x或更高 - **无** (来与节点.js) - **夹克** (用于运行本地内容服务器) - **@dcl/sdk-命令** 全球或当地安装 ## 分发 ### 生产 - 无 : `@dcl/asset-packs@latest` - cdn: (中文(简体) ) `https://builder-items.decentraland.org/contents/:hash` ### 发展 - 无 : `@dcl/asset-packs@next` - cdn: (中文(简体) ) `https://builder-items.decentraland.zone/contents/:hash` ### 部署 **生产部署:** - 触发符 : `main` 分支 - npm: 发布 `@dcl/asset-packs@latest` - CDN: 上传资产到 `https://builder-items.decentraland.org` **发展部署:** - 触发者: 手动注释 `/upload-assets` (仅限成员) - 无 : 通过 S3 测试包可用于 PR 测试 - CDN: 上传资产到 `https://builder-items.decentraland.zone` **说明**:所有资产均按内容处理(hashed),确保不可更改性并正确缓存. ### 地方发展 您可以在本地开发此repo, 并在 Web 编辑器内进行测试 : 到你的机器里去 做这个: 1. 运行 `npm run start` 以监视更改并启动 SDK7 dev 服务器(在端口上) `8001` (默认情况下). 2. 在一个新的终端上,运行 `docker-compose up` 启动本地内容服务器 `http://localhost:9000/asset-packs` 3. 在一个新的终端上,运行 `npm run upload` 上传所有资产到本地内容服务器(复制 `.env.example` 输入 `.env` 如果你以前没有这样做. 4. 复制路径到 `bin/index.js` 在这种回放中( 比如 `/Users/my-user/path/to/creators-hub/packages/asset-packs/bin/index.js`) (中文(简体) ). 转到 `packages/inspector` 在这个单曲中,并做到这一点: 1. 运行 `npm start` 启动本地 dev 服务器。 它应该默认在端口开始 `8000`。 。 。 . 转到 `packages/creator-hub` 在这个单曲中,并做到这一点: 1. 复制 `.env.example` 改为 `.env` 如果你以前没做过的话. 2. 设定 `VITE_INSPECTOR_PORT` (原始内容存档于2018-10-21) (英语). env var in `.env` 将会是 `8000` (这是 `@dcl/inspector` dev 服务器, 我们在上一节开始 . 3. 设定 `VITE_ASSET_PACKS_JS_PORT` 到SDK7在第一节开始运行的端口(`8001`) (中文(简体) ). 4. 设定 `VITE_ASSET_PACKS_JS_PATH` (原始内容存档于2018-10-21) (英语). env var in `.env` 路径 `bin/index.js` 在第一节中复制. 5. 设定 `VITE_ASSET_PACKS_CONTENT_URL` (原始内容存档于2018-10-21) (英语). env var in `.env` 将会是 `http://localhost:9000/asset-packs` (这是我们在第一节开始的内容服务器). 6. 运行 `npm start` 启动应该从端口启动的本地服务器 `3000` 现在你们都准备好了,可以在此repo中开始开发SDK7场景,从本地的构建器开始使用,并通过预览场景来测试,该场景应该使用本地的构建器服务器服务开发的javascript文件. ### 测试检查员的新资产 检查员在运行时间从S3取出资产目录. 若为 `latest/catalog.json` 无法获取(例如,在预置的PR分支上,在CI中,或离线),它自动倒回 `catalog.json` 捆绑在 `@dcl/asset-packs` npm包-所以督察总是会装入. 当你添加一个 **新设** 本地资产不会自动出现在“资产包”标签中,因为CDN和捆绑的目录尚不清楚。 有两个选择: #### 备选方案1——多克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 现存的插头编组处理所有事务. `npm run upload` 现在也上传 `catalog.json` 作为 `asset-packs/latest/catalog.json` 给MineIO, 反射CI对S3所做的. 跟着步骤走 [地方发展](https://npmcn.com/package/%40dcl/asset-packs/#readme-local-development) 在上文中,然后以下列方式开放检查员: ``` http://localhost:8000/?contentUrl=http://localhost:9000/asset-packs ``` 目录列表和所有资产文件都在当地提供——完全端到端测试,不需要远程CDN. #### 备选案文2——通过PR上传到dev CDN 推出你的分行并评论 `/upload-assets` (仅限成员参加)。 CI 将把您分支的所有资产文件上传到开发 CDN (CI) `https://builder-items.decentraland.zone`)并张贴一个确认上传的评论. 然后配置检查器以使用 Dev CDN : ``` VITE_ASSET_PACKS_CONTENT_URL=https://builder-items.decentraland.zone ``` 或当直接打开检查员: ``` http://localhost:8000/?contentUrl=https://builder-items.decentraland.zone ``` 目录指针( E)`latest/catalog.json`)仅在合并到 `main`,因此"资产包"标签仍将显示当前已发布的目录——但资产文件本身将可供加载. ### 解决问题 #### 失踪 `@dcl/ecs` 依赖性 此软件包依赖 `@dcl/ecs` 对于几种类型。 此软件包即使应该如此, 也不会被添加为依赖性, 因为这会在安装时引起问题 `@dcl/sdk@next` 在现场。 问题如下: 1. `@dcl/sdk` - > (中文) `@dcl/ecs` 2. `@dcl/sdk` - > (中文) `@dcl/sdk-commands` - > (中文) `@dcl/inspector` - > (中文) `@dcl/asset-packs` - > (中文) `@dcl/ecs` 当用户安装时 `@dcl/sdk@next` 作为现场,该更新 `@dcl/ecs` 但由于冲突 npm 储存 `@latest` 在节点和模块顶端的版本 `@next` 版本只呼唤 `@dcl/sdk/node_modules`。这会引起运行时间问题. 因此,我们决定 消除明显的依赖性 `@dcl/ecs` 从 `@dcl/asset-packs` 软件包,允许用户安装 `@dcl/sdk@next` 或毫无问题地升级版本. 缺点是,如果在某个项目中使用这个软件包,其中 `@dcl/ecs` 无法使用,它会破裂。 这个包不应该在 德克萨斯州的场景之外使用 所以这不应该是一个问题. ## 相关的结构决定 为了更深入地了解结构和设计决定: - [ADR- 281: 分散工具的项目](https://adr.decentraland.org/adr/ADR-281) - 说明项目抽象、项目类型(稳定、智能、自定义)和技术执行细节. ## 常见问题 ### @dcl/asset-packs 是什么？ 分散式资产包 -- -- 为分散式场景收集3D资产 ### 如何安装 @dcl/asset-packs？ 在项目目录运行 npm install @dcl/asset-packs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@dcl/ecs（^7\.15\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dcl/asset-packs 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dcl/asset-packs 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @dcl/asset-packs 可以商用吗？ @dcl/asset-packs 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @dcl/asset-packs 的下载量有多少？ 根据 npm 官方下载统计，@dcl/asset-packs 在 2026/10/12 – 2026/11/10 这 30 天内被下载 11,908 次，日均约 397 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dcl/asset-packs 还在维护吗？ 最新版本 2\.26\.1 发布于 2026/11/10（2 天前）；至今共发布 293 个版本，其中过去 12 个月发布了 68 个；首次发布于 2023/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。