---
title: 小程序自定义配置
summary: "介绍小程序自定义配置功能，支持将业务配置分离到云端进行集中管理和动态更新。"
tags: [小程序自定义配置, 云端配置下发, 能力配置管理, 模板配置与实例配置]
questions:
  - 小程序自定义配置功能是什么？
  - 自定义配置支持哪些数据类型？
  - 模板配置和实例配置的优先级关系是什么？
  - 如何在 Ray 中使用 getCustomConfig API 获取自定义配置？
  - 自定义配置功能对基础库版本有什么要求？
  - 如何在涂鸦开发者平台创建和管理配置项？
  - 多区域配置如何管理？
  - 使用自定义配置有哪些安全和性能注意事项？
---

## 概述

能力配置功能允许开发者将小程序中的业务配置和技术配置从代码中分离出来，统一存储到云端进行管理。这种方式解决了原有配置硬编码在代码中带来的维护困难和合规问题，实现了配置的集中管理和动态更新。

## 功能特性

- **云端配置管理**：配置信息存储在云端，支持动态更新
- **多种配置类型**：支持链接、布尔、数字、字符串四种配置类型
- **分级配置**：支持模板配置和实例配置，实例配置优先级更高
- **多区域支持**：支持不同地区的配置差异化管理
- **全平台支持**：适用于面板小程序、行业小程序和智能小程序

## 功能模块

### 开发者后台配置管理

在涂鸦开发者平台的后台，您可以进行以下配置管理操作：

#### 1. 模板配置创建

- **权限限制**：只有模板可以创建配置，实例无法直接创建
- **配置参数**：每个配置项需要设置以下参数：
  - `code`：配置项的唯一标识符
  - `说明`：配置项的详细描述
  - `类型`：配置项的数据类型
  - `默认值`：配置项的默认值
  - `实例是否可编辑`：控制配置是否可在实例编辑

#### 2. 配置类型

系统支持以下四种配置类型：

| 类型   | 说明         | 示例                      |
| ------ | ------------ | ------------------------- |
| 链接   | URL 地址配置 | `https://example.com/api` |
| 布尔   | 开关类型配置 | `true` 或 `false`         |
| 数字   | 数值类型配置 | `100`、`3.14`             |
| 字符串 | 文本类型配置 | `"Hello World"`           |

#### 3. 配置透出机制

- **透出条件**：只有设置为"在实例可编辑"的配置才会在实例中显示
- **适用范围**：面板小程序、行业应用小程序无法进行实例透出
- **优先级**：实例配置 > 模板配置（实例配置优先，模板配置兜底）

#### 4. 多区域配置

- **区域支持**：支持不同地区的配置差异化
- **配置方式**：暂时无法支持一键同步多区，需要手动配置每个区域
- **管理便捷**：可以针对不同区域设置不同的配置值

## 配置管理指南

### 1. 创建配置

1. 登录 [涂鸦开发者平台](https://platform.tuya.com/miniapp/)
2. 进入小程序管理页面
3. 选择对应的模板小程序
4. 进入"能力配置"管理页面
5. 点击"新增配置"按钮
6. 填写配置信息：
   - **配置代码**：英文标识符，建议使用下划线命名法
   - **配置说明**：详细描述配置的用途和作用
   - **配置类型**：选择合适的数据类型
   - **默认值**：设置合理的默认值
   - **实例可编辑开关**：根据需要选择是否对实例开放编辑功能

### 2. 管理配置

#### 2.1 修改配置

- 模板配置可以直接修改
- 实例配置优先级更高，会覆盖模板配置
- 配置修改后，会在下一次打开小程序时生效

#### 2.2 删除配置

- 删除配置前请确保小程序代码中已移除相关引用
- 删除后无法恢复，请谨慎操作

#### 2.3 多区域管理

- 不同区域可以设置不同的配置值
- 需要针对每个区域单独配置
- 建议建立配置文档，记录各区域的配置差异

### 3. 使用方法

详情可参考[自定义配置 API](/cn/miniapp/develop/ray/api/base/container/getCustomConfig) 文档。

#### Ray

```javascript
// @ray-js/ray（版本 >= 1.7.22）提供了 getCustomConfig API，用于获取自定义配置信息
import { getCustomConfig } from '@ray-js/ray';

getCustomConfig({
  success: (res) => {
    console.log('获取配置成功:', res);

    // 直接使用配置
    const timeout = res.timeout || 5000;
    const enableDebug = res.enableDebug || false;
    const helpUrl = res.helpUrl || '';
  },
  fail: (err) => {
    console.error('获取配置失败:', err);
  }
});
```

#### 原生小程序

```javascript
// 基础库（版本 >= 2.29.0）提供了 ty.getCustomConfig 方法用于获取自定义配置信息
ty.getCustomConfig({
  success: (res) => {
    console.log('获取自定义配置成功:', res);
    const customConfigs = res || {};

    // 使用配置
    const apiEndpoint = customConfigs.api_endpoint || 'https://default-api.com';
    const enableDebug = customConfigs.enable_debug || false;
    const maxRetryCount = customConfigs.max_retry_count || 5;

    // 应用到业务逻辑中
    this.setData({
      apiUrl: apiEndpoint,
      debugMode: enableDebug,
      retryLimit: maxRetryCount
    });
  },
  fail: (err) => {
    console.error('获取自定义配置失败:', err);
    // 使用默认配置
    this.setData({
      apiUrl: 'https://default-api.com',
      debugMode: false,
      retryLimit: 5
    });
  }
});
```

## 注意事项

### 1. 兼容性

- 基础库版本需要 >= 2.29.0
- 老版本小程序可能无法使用此功能

### 2. 性能优化

- 配置数据建议在应用启动时加载并缓存
- 避免频繁调用 `ty.getCustomConfig()` 接口
- 合理设置配置的默认值，确保在网络异常时小程序仍能正常运行

### 3. 安全考虑

- 敏感信息（如密钥、密码）不应通过自定义配置传递
- 配置值会明文传输，请注意数据安全
- 建议对重要配置进行加密处理