#涂鸦 CDN 资源使用

#版本限制

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

#功能描述

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

#配置 CDN

#工程配置

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

{
  "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，例如：

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

#使用限制

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

#功能说明

上传文件：

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

删除文件：

1. 先在 cdnImage.json 中删除对应的 key-value
2. 前往小程序开发者平台删除文件释放额度

#手动管理示例

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

操作步骤：

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

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

3. 在代码中使用：

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

const logoUrl = getCdnUrl('logo.png', cdnImage)

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

操作步骤：

1. 前往小程序开发者平台上传图片文件

2. 上传成功后，点击"复制"按钮，得到 CDN 路径：

smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg

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

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

   

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

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

5. 在代码中使用：

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

const bannerUrl = getCdnUrl('banner.png', cdnImage)

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

场景一：彻底删除文件

假设不再需要 banner.png：

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

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

2. 前往小程序开发者平台删除对应的 CDN 文件，释放存储额度

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

场景二：替换文件

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

1. 前往小程序开发者平台上传新图片

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

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

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

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

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

// key 不变，但会加载新图片
const bannerUrl = getCdnUrl('banner.png', cdnImage)

#项目中使用

#基本用法

Ray 提供了 getCdnUrl 方法，图片会根据当前区域自动替换为对应的 CDN 地址。

步骤 1：导入依赖

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

步骤 2：获取 CDN 地址

// 使用完整的 key 路径
const logoUrl = getCdnUrl('logo.png', cdnImage)

步骤 3：在组件中使用

import { Image } from '@ray-js/ray'

<Image src={logoUrl} style={{ width: 100, height: 100 }} />

#完整示例

假设 cdnImage.json 内容如下：

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

在 React 组件中使用：

import React from 'react'
import { Image, View, Text, getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

const imageStyles = {
  base: {
    display: 'block',
  },
  logo: {
    width: 100,
    height: 100,
    marginBottom: 20,
    borderRadius: 8,
    boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
  },
  banner: {
    width: 200,
    height: 200,
    borderRadius: 12,
    boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
    border: '1px solid #eee',
  },
}

export default function Home() {
  // 预先处理 CDN URL，避免重复调用
  const logoUrl = getCdnUrl('logo.png', cdnImage)
  const bannerUrl = getCdnUrl('1.png', cdnImage)

  return (
    <View>
      <Text>Hello CDN</Text>
      <Image src={logoUrl} style={{ ...imageStyles.base, ...imageStyles.logo }} />
      <Image src={bannerUrl} style={{ ...imageStyles.base, ...imageStyles.banner }} />
    </View>
  )
}

#注意事项

• 建议在组件外部或 useMemo 中预先处理 URL，避免每次渲染都调用
• CDN 地址会根据用户所在区域自动选择最近的节点，提升加载速度

#常见问题

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

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

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

Q2: 如何释放 CDN 额度？

A: 必须前往小程序开发者平台删除文件才能释放额度。仅在项目中删除 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. 前往开发者平台查看已上传的文件，手动重建映射关系