TvT.js
目录
主题颜色

配置与接口

📂 项目结构说明

├── assets/                  # 素材根目录
│   ├── textures/           # 材质贴图
│   ├── images/             # 普通图片
│   ├── videos/             # 视频资源
│   ├── env/                # 环境资源
│   ├── json/               # JSON 配置
│   └── other/              # 其他资源
├── src/
│   ├── cli.js              # 命令行参数与运行模式
│   ├── scanAssets.js       # 素材扫描与 config 生成
│   ├── server.js           # HTTP、CORS 与静态资源服务
│   ├── upload.js           # 本地上传处理
│   ├── previewPage.js      # 素材管理与预览页面
│   ├── buildStaticSite.js  # 纯静态发布包构建
│   └── mime.js             # MIME 类型映射
├── assetServeWatch.js      # 命令行入口
└── package.json

⚙️ 命令行参数

node assetServeWatch.js [运行模式] [选项]
参数说明默认值
-serve、--serve启动本地 HTTP 调试服务关闭
-build、--build构建可部署的静态站点关闭
-p、--path <dir>素材根目录./assets
-port、--port <number>调试服务端口4100
-host、--host <host>调试服务监听地址0.0.0.0
-maxUploadSize、--max-upload-size <MB>单文件上传上限512
-out、--out <file>单独生成 config 时的输出文件<素材目录>/asset-config.json
-dist、--dist <dir>静态构建输出目录./dist
-baseUrl、--base-url <url>config 中资源 URL 的公开根地址空
-h、--help显示帮助—

--serve 与 --build 不能同时使用。

🧾 config 结构

资源清单示例：

{
  "schemaVersion": "tvt-asset-manager-serve@0.1.0",
  "generatedAt": "2026-07-02T00:00:00.000Z",
  "rootName": "assets",
  "baseUrl": "http://localhost:4100",
  "counts": {
    "total": 1,
    "texture": 1
  },
  "assets": [
    {
      "id": "texture-textures-warning-line-a1b2c3d4",
      "name": "warning-line.png",
      "type": "texture",
      "category": "textures",
      "path": "textures/warning-line.png",
      "url": "http://localhost:4100/assets/textures/warning-line.png",
      "previewUrl": "http://localhost:4100/assets/textures/warning-line.png",
      "mime": "image/png",
      "size": 1024,
      "updateTime": "2026-07-02T00:00:00.000Z",
      "hash": "完整的 SHA-256 文件哈希"
    }
  ]
}

顶层字段

字段说明
schemaVersion清单结构版本
generatedAt本次扫描完成时间，ISO 8601 格式
rootName素材根目录名称
baseUrl资源服务公开根地址
counts资源总数及各类型数量
assets资源明细列表

单个资源字段

字段说明
id根据资源类型和相对路径生成的稳定 ID
name文件名
type统一资源类型
category素材根目录下的第一级目录
path相对于素材根目录的路径
url资源完整访问地址
previewUrl可预览资源的地址；不可预览类型为空字符串
mimeHTTP MIME 类型
size文件大小，单位为字节
updateTime文件最后修改时间
hash文件内容的 SHA-256 哈希

资源相对路径不变时，id 会保持稳定；文件内容变化时，hash 会同步变化。

🗂️ 类型识别规则

服务优先根据素材的第一级目录判断类型，再根据扩展名兜底：

目录生成的 type
textures、texturetexture
images、imageimage
videos、videovideo
env、hdr、sky、skyboxenv
jsonjson
otherother

可预览类型为 env、image、texture 和 video。未识别的文件统一归入 other。

扫描时会忽略：

  • 隐藏文件与隐藏目录
  • .DS_Store
  • .gitkeep
  • 已生成的 asset-config.json

🔌 调试服务接口

方法路径说明
GET/素材管理与预览页
GET/preview素材管理与预览页别名
GET/config实时扫描并返回资源清单
POST/upload?category=<category>以 multipart/form-data 上传一个或多个 files
GET/assets/<relative-path>读取具体素材
HEAD/assets/<relative-path>读取素材响应头和元信息
OPTIONS*CORS 预检

上传成功时返回 HTTP 201：

{
  "uploaded": [
    {
      "id": "texture-textures-demo-a1b2c3d4",
      "path": "textures/demo.png",
      "url": "http://localhost:4100/assets/textures/demo.png"
    }
  ],
  "config": {
    "schemaVersion": "tvt-asset-manager-serve@0.1.0",
    "assets": [
      {
        "path": "textures/demo.png"
      }
    ]
  }
}

实际返回的 uploaded 项包含完整资源字段，config 为上传后的完整最新清单。

📦 静态发布入口

构建产物提供内容相同的多个 config 入口：

/config
/config.json
/asset-config.json
/assets/asset-config.json

推荐对外使用 /config.json。这些别名只属于静态构建产物；本地调试服务使用实时接口 /config。

🌐 CORS 配置

本地调试服务已返回：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,HEAD,POST,OPTIONS
Access-Control-Allow-Headers: Content-Type, Range

将 dist/ 部署到自己的服务器时，也需要为 config 和 assets 配置允许编辑器域名访问的 CORS 响应头。视频等大文件建议保留 Range 请求支持。

🔒 使用边界

  • 上传能力仅用于本地调试，不包含鉴权与审核。
  • 静态发布版本不提供上传或删除接口。
  • 服务不会修改素材文件内容。
  • 构建输出目录与素材目录必须相互独立，防止覆盖素材。
  • 新增、替换或删除素材后，需要重新构建才能更新静态发布站点。
本页目录