---
title: 涂鸦 CDN 资源使用
summary: "介绍涂鸦 CDN 资源的上传、配置和使用方法，支持通过 IDE 和开发者平台两种方式管理。"
questions:
  - 使用涂鸦 CDN 功能需要满足哪些版本限制？
  - 涂鸦 CDN 的存储额度是多少，如何计算？
  - 如何通过 IDE 上传文件到涂鸦 CDN？
  - 如何通过开发者平台上传文件到涂鸦 CDN？
  - cdnImage.json 文件是如何自动生成的？
  - 如何在小程序模板中使用 cdn.url() 引用 CDN 资源？
  - 删除涂鸦 CDN 文件的正确流程是什么？
  - 如何替换已上传的涂鸦 CDN 文件？
  - 100MB 额度是单个项目还是所有项目共享的？
  - 误删 cdnImage.json 文件后应如何恢复？
---

## 涂鸦 CDN 资源使用

### 版本限制

- 基础库版本需 `>=2.26.0`
- @ray-js/ray 版本需 `>=1.6.10`
- 开发者工具版本需 `>=0.10.0`
- **不可与外部 CDN 功能同时使用**

### 功能描述

为了减少小程序包体积，小程序提供了 CDN 资源使用功能。开发者可以将项目中的静态资源(如图片、音频等)上传到 CDN，运行时会自动替换为对应的 CDN 地址。

### 配置 CDN

#### 工程配置

在 `project.tuya.json` 中声明需上传 CDN 的配置文件的存放目录。

```json
{
  "projectname": "miniApp",
  "i18n": true,
  "miniprogramRoot": "app/",  # 小程序源码
+ "publicRoot": "cdn/",    # 需上传 CDN 的静态资源存放目录
  "projectId": "********",
  "baseversion": "2.10.6",
  "dependencies": {
    "BaseKit": "3.0.3",
    "MiniKit": "3.0.6",
    "BizKit": "3.0.6"
  }
}
```

在项目根目录内新增 `cdn` 目录, 文件内容如下:

```
├── package.json
├── project.tuya.json
└── cdn
```

#### 开发者工具上传 CDN
在开发者工具选择文件上传之后，会自动在 cdn 目录下生成 `cdnImage.json`，例如：

```json
{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "1.png": "smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg"
}
```

#### 使用限制

- 资源会先推送至中国区，然后同步到其他区域
- 当前仅支持存储 100MB 的静态资源

#### 功能说明

| 操作 | IDE | 开发者平台 |
|------|-----|-----------|
| 初始化配置文件 | ✓ | - |
| 上传文件 | ✓ | ✓ |
| 查看文件 | - | ✓ |
| 删除文件 | - | ✓ |

**上传文件：**

- IDE 上传：会自动生成 Key-Value 并写入 `cdnImage.json`，如需修改 key，请手动编辑该文件
- 平台上传：需手动在 `cdnImage.json` 中添加对应的 Key-Value 映射

**删除文件：**

1. 先在 `cdnImage.json` 中删除对应的 key-value
2. 前往[小程序开发者平台](https://platform.tuya.com/miniapp)删除文件释放额度

#### 手动管理示例

##### 示例一：通过 IDE 上传文件

**操作步骤：**

1. 在 IDE 中点击"上传 CDN 文件"按钮，选择本地图片文件 `logo.png`
2. IDE 自动生成 `cdnImage.json` 文件，内容如下：

```json
{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg"
}
```

3. 在小程序代码中使用：

```xml
<view>
  <image src="{{cdn.url('logo.png')}}"></image>
</view>
```

##### 示例二：通过开发者平台上传文件

**操作步骤：**

1. 前往[小程序开发者平台](https://platform.tuya.com/miniapp)上传图片文件

<Image src='/images/guide/cdn/upload.png'/>
<Image src='/images/guide/cdn/upload-button.png'/>

2. 上传成功后，点击"复制"按钮，得到 CDN 路径：
<Image src='/images/guide/cdn/copy_link.png'/>
例如复制的链接为：
```
smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg
```

3. 如果本地没有 `cdnImage.json` 文件，先初始化它

   点击 IDE 中的"初始化 cdnImage.json 文件"按钮：

   <Image src='/images/guide/cdn/init_cdn.png'/>

4. 在项目的 `cdnImage.json` 中手动添加映射：

```json
{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "banner.png": "smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg"
}
```

5. 在小程序代码中使用：

```xml
<view>
  <image src="{{cdn.url('banner.png')}}"></image>
</view>
```

##### 示例三：删除或替换 CDN 文件

**场景一：彻底删除文件**

假设不再需要 `banner.png`：

1. 先在 `cdnImage.json` 中删除对应的记录：

```json
{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg"
  // 已删除 "banner.png" 这一行
}
```

2. 前往[小程序开发者平台](https://platform.tuya.com/miniapp)删除对应的 CDN 文件，释放存储额度

3. 确保代码中不再引用 `banner.png`，避免图片加载失败

**场景二：替换文件**

假设需要更新 `banner.png` 为新图片：

1. 前往[小程序开发者平台](https://platform.tuya.com/miniapp)上传新图片

2. 删除旧的 CDN 文件（释放额度）

3. 在 `cdnImage.json` 中更新 CDN 路径：

```json
{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "banner.png": "smart/miniapp/static/bay1754039465669v6sh/1755999999000newfile.jpeg"
}
```

4. 代码中的引用保持不变，图片会自动使用新的 CDN 地址：

```xml
<view>
  <!-- key 不变，但会加载新图片 -->
  <image src="{{cdn.url('banner.png')}}"></image>
</view>
```

### 项目中使用

#### 基本用法

在模板中使用 `cdn.url()` 方法获取 CDN 地址：

```xml
<view>
  <!-- 使用 cdnImage.json 中定义的 key -->
  <image src="{{cdn.url('logo.png')}}"></image>
  <image src="{{cdn.url('banner.png')}}"></image>
</view>
```

#### 完整示例

假设 `cdnImage.json` 内容如下：

```json
{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "icon/home.png": "smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae03.jpeg"
}
```

在小程序中使用：

```xml
<view>
  <!-- 图片会自动替换为对应区域的 CDN 地址 -->
  <image src="{{cdn.url('logo.png')}}" />
  <image src="{{cdn.url('icon/home.png')}}" />
</view>
```

**注意：**
- `cdn.url()` 的参数必须与 `cdnImage.json` 中的 key 完全一致
- 图片会根据用户所在区域自动使用对应的 CDN 节点，提升加载速度

### 常见问题

**Q1: 100MB 是单个项目的额度还是所有项目共享的额度？**

A: 100MB 是当前空间下**所有小程序项目的总额度**，不是单个项目的额度。

- 同一空间内的多个小程序项目会共享这 100MB 的存储空间
- 如有空间授权，以父账号（空间所有者）的额度为准
- 例如：A 授权给 B，B 在 A 空间中操作时，使用的是 A 账号的 CDN 额度

**Q2: 如何释放 CDN 额度？**

A: 必须前往[小程序开发者平台](https://platform.tuya.com/miniapp)删除文件才能释放额度。**仅在项目中删除 `cdn/cdnImage.json` 文件或其中的记录，不会释放 CDN 额度**。

正确的删除流程：
1. 先在项目的 `cdnImage.json` 中删除对应的 key-value（避免代码引用失效）
2. 前往开发者平台删除对应的 CDN 文件（释放额度）

**Q3: 如果额度不足怎么办？**

A: 
1. 前往开发者平台查看已上传的文件，删除不再使用的资源释放额度
2. 在上传前优化图片大小，使用压缩工具（如 TinyPNG）减小文件体积

**Q4: 误删了 `cdnImage.json` 文件怎么办？**

A: `cdnImage.json` 只是本地的映射文件，删除后：
1. 开发者平台的 CDN 文件仍然存在，额度不会释放
2. 可以重新在 IDE 中点击"初始化 cdnImage.json 文件"按钮生成空模板
3. 前往开发者平台查看已上传的文件，手动重建映射关系