---
title: 三方 CDN 资源使用
summary: "介绍三方 CDN 资源的配置方法，包括多区域 CDN 地址映射及在项目中通过 cdn.url() 引用。"
questions:
  - 使用三方 CDN 功能需要满足哪些版本要求？
  - 如何在 project.tuya.json 中配置三方 CDN 的静态资源目录？
  - cdnImage.json 文件需要配置哪些区域标识？
  - 三方 CDN 与涂鸦 CDN 可以同时使用吗？
  - 如何在小程序模板中使用 cdn.url() 获取 CDN 资源地址？
  - cdnImage.json 中欧洲区（EU）地址的特殊兜底作用是什么？
  - 三方 CDN 功能支持哪些主流 CDN 服务商？
  - publicRoot 字段在 project.tuya.json 中的作用是什么？
  - 配置 CDN 地址时需要注意哪些事项？
  - 图片如何根据当前区域自动替换为对应的 CDN 地址？
---

## 三方 CDN 资源使用

### 版本限制

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

### 功能描述

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

### 上传 CDN

开发者需要自行选择 CDN 服务商并上传资源。以下是一些主流的 CDN 服务商供参考：

- [腾讯云 CDN](https://cloud.tencent.com/product/cdn)
- [阿里云 CDN](https://www.aliyun.com/product/cdn)
- [AWS CloudFront](https://aws.amazon.com/cn/cloudfront/)
- [Cloudflare CDN](https://www.cloudflare.com/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` 目录, 并增加 `cdnImage.json` 文件, 文件内容如下:

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

`cdnImage.json` 需要配置每个区域对应的 CDN 地址，例如：

需配置的多区标识：

- AY：中国区
- AZ：美国区
- EU：欧洲区
- IN：印度区
- UE：美东
- WE：西欧
- RU：俄罗斯

```json
{
  // 中国区
  "AY": {
    "/cdn/logo.png": "https://images.tuyacn.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://images.tuyacn.com/smart/miniapp/static/1670384599c63a79781fd.png"
  },
  // 美国区
  "AZ": {
    "/cdn/logo.png": "https://usimagesd1448c85ulz2o4.cdn5th.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://usimagesd1448c85ulz2o4.cdn5th.com/smart/miniapp/static/1670384599c63a79781fd.png"
  },
  // 欧洲区
  "EU": {
    "/cdn/logo.png": "https://euimagesd2h2yqnfpu4gl5.cdn5th.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://euimagesd2h2yqnfpu4gl5.cdn5th.com/smart/miniapp/static/1670384599c63a79781fd.png"
  },
  // 印度区
  "IN": {
    "/cdn/logo.png": "https://inimagesd1jqokb9wptk2t.cdn5th.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://inimagesd1jqokb9wptk2t.cdn5th.com/smart/miniapp/static/1670384599c63a79781fd.png"
  },
  // 美东
  "UE": {
    "/cdn/logo.png": "https://usimagesd1448c85ulz2o4.cdn5th.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://usimagesd1448c85ulz2o4.cdn5th.com/smart/miniapp/static/1670384599c63a79781fd.png"
  },
  // 西欧
  "WE": {
    "/cdn/logo.png": "https://d2h2yqnfpu4gl5.cdn5th.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://d2h2yqnfpu4gl5.cdn5th.com/smart/miniapp/static/1670384599c63a79781fd.png"
  },
  // 俄罗斯
  "RU": {
    "/cdn/logo.png": "https://euimagesd2h2yqnfpu4gl5.cdn5th.com/smart/miniapp/static/1664528993779f7997c9a.png",
    "/cdn/1.png": "https://euimagesd2h2yqnfpu4gl5.cdn5th.com/smart/miniapp/static/1670384599c63a79781fd.png"
  }
}
```

**注意：**

1.  上述配置的 CDN 地址，需要与上传的 CDN 地址一致，否则会导致 CDN 资源替换失败。
2.  欧洲区（EU）的 CDN 地址为兜底地址，当其他区域 CDN 地址不存在时，会使用欧洲区的 CDN 地址。

### 项目中使用

图片会根据当前区域自动替换为对应的 CDN 地址。

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