---
title: 面板小程序
summary: "面板小程序开发快速入门，涵盖环境搭建、产品创建、工程初始化、调试到审核上线的完整流程。"
tags: [面板小程序快速开始, Ray面板开发教程, IDE创建面板项目, 面板小程序发布流程]
questions:
  - 开发面板小程序需要安装哪些工具和环境？
  - 如何在涂鸦开发者平台创建产品并定义功能点？
  - 面板、产品和智能设备之间是什么关系？
  - 如何通过 Tuya MiniApp IDE 初始化面板小程序工程？
  - 面板小程序如何使用面板工具进行虚拟设备调试？
  - 面板小程序的真机调试流程是怎样的？
  - 如何上传面板小程序代码并设为体验版？
  - 面板小程序的体验二维码如何生成和使用？
  - 面板小程序的审核上线流程是什么？
  - 如何将面板小程序关联到产品上？
---

{<Block>

  <a href="https://m.bilibili.com/video/BV1Bm421n7UF?buvid=Y54CE05EC304EC244CEDB4E1F0CA2EF7C540&from_spmid=main.space-contribution.0.0&is_story_h5=false&mid=rIwAEcVozpaI2Le7cX65vw%3D%3D&p=1&plat_id=116&share_from=ugc&share_medium=iphone&share_plat=ios&share_session_id=C4E176DB-A91A-439A-8F1F-386F50999C06&share_source=WEIXIN&share_tag=s_i&spmid=united.player-video-detail.0.0&timestamp=1715075255&unique_k=S2l6e4y&up_id=1394005610">
    面板小程序视频教程
  </a>
</Block>}

{<Block>

  <a href="https://developer.tuya.com/cn/miniapp-codelabs/codelabs/panelmore-guide/index.html#0">
    如需更好的阅读体验，请移步 Codelabs。
  </a>
</Block>}

## 一、搭建环境

### 前置条件

- 在开发小程序之前，请确保电脑上已经安装 node 运行环境。可前往 [Node.js 官网](https://nodejs.org/en) 下载安装。

### 安装编辑器

面板小程序开发前，请您按需自行下载安装下列推荐的编辑器：

- Visual Studio Code：（推荐）自带格式化、代码跳转等常用功能，社区贡献与活跃度较高。
- WebStorm：集成度较高的 IDE。
- Sublime Text：小巧轻便。

### 安装 App

> 如果需要安装特定的 App 版本，请通过 [涂鸦开发者平台提交工单](https://service.console.tuya.com/8/3/list?source=support_center) 联系我们，寻求支持。

**iOS:**

前往 [App Store 上的 “智能生活”](https://apps.apple.com/cn/app/id1586125720)，或通过手机上官方 App Store 应用下搜索 `智能生活 App` 并点击下载安装即可。

**安卓:**

前往 [应用宝上的 ”智能生活“](https://a.app.qq.com/o/simple.jsp?pkgname=com.tuya.smartlifeiot)，或在手机端通过各大厂商提供的应用商店下搜索 `智能生活 App` 并点击下载安装即可。

### 安装 Tuya MiniApp IDE

> Tuya MiniApp IDE 可以帮助您创建、开发、调试、上传小程序项目。

前往 [Tuya MiniApp IDE](/cn/miniapp/devtools/tools/download) 下载并安装 Tuya MiniApp IDE 的最新版本。

### 安装 NVM

> NVM 可以帮助您管理多 Node 版本，注意首次安装，需要根据提示设置环境变量

1. 打开终端。

2. 安装 [NVM](https://github.com/nvm-sh/nvm)。

   ```shell
   	curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.36.0/install.sh | bash
   ```

3. 输入 `nvm -v`，确认 NVM 已正常安装，若输出版本号，则表明安装成功（检查 Node.js 版本号在 18.0.0 以上，若低于 18.0.0，则需要安装更高版本，您可参考 4），若报错 `nvm: command not found`，您可参考文末常见问题的解决方法。

4. 输入 `nvm install 18.20.8 `，安装 Node.js 18.20.8 版本。

5. （可选）支持通过 `nvm use` 命令切换至指定 Node.js 版本。（建议安装 Node.js 18.20.8 及以上版本。）

   ```shell
   	nvm use 18.20.8
   ```

### 安装 Yarn

> 如果已安装过 yarn 或者已使用 npm、pnpm 等依赖管理工具，可忽略本内容

1. 打开终端。

2. 输入 `npm install -g yarn`，安装 Yarn。

3. 输入 `yarn -v `，确认 Yarn 已正常安装。

## 二、创建产品

### 理解关系

> 面板作为 IoT 智能设备在 App 终端上的产品形态，创建产品之前，首先来了解一下什么是面板，以及和产品、设备之间的关系。

1. `面板` 是运行在 `智能生活 App`、`OEM App（涂鸦定制 App）` 上的界面交互程序，用于控制 `智能设备` 的运行，展示 `智能设备` 实时状态。
2. `产品` 将 `面板` 与 `智能设备` 联系起来，产品描述了其具备的功能、在 App 上面板显示的名称、智能设备拥有的功能点等。
3. `智能设备` 是搭载了 `涂鸦智能模组` 的设备，通常在设备上都会贴有一张二维码，使用 `智能生活 App` 扫描二维码，即可在 App 中获取并安装该设备的控制 `面板`。
4. `产品`、`面板`、`设备` 之间的关系可参考下图。

<Image
  src="/images/panel/panel.png?t=1"
  style={{
    borderRadius: '10px',
    width: '618px',
    boxShadow: '0 0 5px rgba(0,0,0,0.3)',
  }}
/>

<Callout type="info" emoji="ℹ️">
  简单来说，<br/>
  **智能小程序** 可以实现任何的功能，比如天气小程序、音乐小程序、计算器小程序等等，可以在 App 的任何入口打开。<br/>
  **面板小程序** 则是依赖设备的，他是设备的控制面板，用于控制设备的开关、模式、亮度等功能，一般只能在 App 的设备列表里打开，在打开的同时会注入一些预置的设备逻辑，如设备对应的产品多语言以及当前打开的设备状态。
</Callout>

### 操作步骤

> 由于产品定义了面板和设备所拥有的功能点，所以在开发一个智能设备面板之前，我们首先需要创建一个产品，定义产品有哪些功能点，然后面板中再根据这些功能点一一实现。

在涂鸦开发者平台上创建产品的操作步骤如下：

1. 注册登录 [涂鸦开发者平台](https://platform.tuya.com)。

2. 左侧导航栏中，单击 [产品 > 产品开发 > 创建产品](https://platform.tuya.com/pmg/solution)，以 **大家电** 为例，选择 **标准类目**，选择 **大家电** > **空调**。

<Image src='https://images.tuyacn.com/content-platform/hestia/16667782563bf9275788d.gif'/>

3. 填写产品名称，其余选项默认即可，单击 **创建产品** 按钮，完成产品创建。

4. 创建完成产品后，进入 **功能定义** 这个产品开发步骤页面。在 **标准功能** 中，您可以单击 **添加功能**，查看空调类目下可选的标准功能点。单击 **全部选择** > **确定**，完成产品初始功能点设置。

<Image src='https://images.tuyacn.com/content-platform/hestia/16667796716e3953ec733.gif'/>

- 关于创建产品的更多详情，可查阅 [涂鸦开发者平台 > 创建产品](https://developer.tuya.com/cn/docs/iot/create-product?id=K914jp1ijtsfe)。
- 如需进一步了解产品功能，可查阅 [涂鸦开发者平台 > 产品功能](https://developer.tuya.com/cn/docs/iot/define-product-features?id=K97vug7wgxpoq)。

## 三、初始化工程

### 前提

您需要拥有涂鸦开发者账号，然后以开发者身份入驻 涂鸦小程序 开发者平台，才能创建小程序。如果尚未拥有涂鸦账户，请前往 [注册涂鸦开发者账号](https://auth.tuya.com/register)。

### 创建面板小程序

1. 登录 [涂鸦小程序 开发者平台](https://platform.tuya.com/miniapp/)，可以看到 **我的小程序** 列表页面。
2. 在小程序列表页面，单击 **新建** 按钮。
3. 填写小程序名称、头像、小程序类型等相关信息，单击 **创建**，注意选择 **面板小程序**。

<Image src='https://images.tuyacn.com/content-platform/hestia/1728288290d48eecb1b51.jpg'/>

### 初始化项目工程

1. 启动 Tuya MiniApp IDE ，登录开发者账号，新建小程序。
2. 根据提示设置以下信息后，单击 **确认**，进入工程模板选择界面。
   - **项目路径**：当前生成的工程要放置到哪个文件路径。
   - **项目名称**：当前生成的工程项目名称。
   - **关联小程序**：此前在平台创建完毕的项目。

     > 当前登录 Tuya MiniApp IDE 的账号需要在 涂鸦小程序 开发者平台中被授予对应的开发者权限，并关联面板小程序。这样，您才能使用该账号在 Tuya MiniApp IDE 里进行开发、调试、上传。

   - **关联产品**：当前面板小程序需要关联的产品，即此前在 **创建产品** 步骤生成的产品。

<Image src='https://images.tuyacn.com/fe-static/docs/img/a28a04cb-ff6a-4210-a127-f6a19aac39b9.png'/>

3. 根据您的面板小程序开发需求，选择合适的预置模板，然后点击 **创建** 。具体说明如下：
   - 将鼠标移动到模板上时，会显示对应的模板二维码，您可以通过扫码进行体验。
   - 点击 "源码" 会自动跳转到相应的 GitHub 仓库（如有）。
   - 点击 "教程" 会自动跳转到相应的 Codelabs 教程（如有）。

   > 品类模板通常包含特定的产品功能点要求。如果需要使用，请确保这些功能点已定义完毕。如果没有合适的品类模板，建议使用面板 SDM 通用模板。

<Image src='https://images.tuyacn.com/fe-static/docs/img/4613f724-fd19-4403-baaf-b6554ab408b6.png'/>

4. 完成创建后，会自动进入面板小程序的开发调试界面。至此，恭喜您已经完成初始化项目。

<Image src='https://images.tuyacn.com/fe-static/docs/img/686cedc2-7a2a-4f6b-8c66-00acfb8ac517.png'/>

## 四、开发调试

### 启动项目

找到此前生成的工程目录并进入，`Tuya MiniApp IDE ` 会自动完成安装依赖与项目启动面板小程序。

> 若导入项目后 `Tuya MiniApp IDE` 未自动安装依赖并启动面板小程序，可以自行检查，是否 `project.tuya.json` 文件中存在 `devMode: ray` 的参数。

```json
{
  "devMode": "ray"
}
```

### 启用面板工具

在完成启动项目之后，您会发现修改代码已进行实时编译，但在 Tuya MiniApp IDE 上仍无法实时看到项目的 UI 布局情况。

这是因为面板小程序的运行需要 **依赖一个对应的虚拟设备**，因此我们需要先启用面板工具。

1. 找到位于 Tuya MiniApp IDE 右上角的 `账号` 按钮，通过智能生活 App 进行扫码授权。

<Image src='/images/ide/c-login.png'/>

2. 找到位于 Tuya MiniApp IDE 上方的 `插件 > 面板工具` 按钮，会出现如下设备列表页面。面板工具支持 `虚拟设备调试`、`真实设备调试`、`群组设备调试` 三种调试模式。

<Image src='https://images.tuyacn.com/content-platform/hestia/1728295132fbcc3e947bd.jpg'/>

**2.1. 虚拟设备调试**

可在设备列表中选择需要调试的设备虚拟设备（设备卡片标签中含有 `虚拟设备` 标签），进入调试界面。若设备列表中没有可以用于调试的设备，可点击右上角 `添加虚拟设备` 按钮进入虚拟设备扫码添加界面。

<Image src='/images/panel/virtual-device-bind.png'/>

继续使用智能生活 App 进行扫码，完成后，页面会跳转到以下界面，并重新加载左侧面板小程序。此时，您就可以正式开始开发自己的面板小程序。

> 注意，App 上扫码后，会自动进入当前产品绑定的默认面板，并不是您当前正在开发的面板小程序。如果需要在 App 上进行开发调试，请参考下方的真机调试。

<Image src='https://images.tuyacn.com/content-platform/hestia/172829498783d446def84.jpg'/>

**2.2. 真实设备调试**

若已在 App 中添加过真实设备，将会出现在设备列表中（设备卡片标签中含有 `真实设备` 标签），在设备列表中点击该设备卡片即可进入该真实设备调试界面。若无需要调试的设备，可通过智能生活 App 配网功能添加新设备。插件目前支持 Wi-Fi 类，及通过网关连接的 Zigbee、Mesh、SigMesh、Beacon 等协议的子设备，以及 TuyaLink 协议的开发与调试。

<Image src='https://images.tuyacn.com/content-platform/hestia/1728295132fbcc3e947bd.jpg'/>

**2.3. 群组设备调试**

群组设备需要通过智能生活 App 进行群组创建，创建后会显示到设备列表中（设备卡片标签中含有 `群组` 标签），在设备列表中点击该群组卡片即可进入该群组设备调试界面。

**2.4. 虚拟设备、真实设备及群组设备控制在插件功能上的差异**

- 虚拟设备支持控制面板下发指令来模拟设备上报功能，真实设备及群组设备不支持该功能。
- 虚拟设备支持解除 IDE 插件绑定并重新扫码增加设备的功能，真实设备及群组设备不支持该功能。
- 虚拟设备支持设备在线状态模拟上报功能，真实设备及群组设备不支持该功能。

### 真机调试

> 如当前开发阶段不需要使用到真实 App 环境，可暂时跳过该步骤。

目前 IDE 内置插件版本已更新到 v1.4.0，针对于 v1.4.0 及以上插件版本，可从插件首页设备列表中直接进入设备调试界面，此时无需输入任何参数，点击真机调试按钮（IDE 菜单栏中间第三个按钮）即可进入进行扫码调试。 也无需修改编译参数中的 `deviceId` 或 `groupId`。对于仅支持蓝牙直连的设备，暂不支持操作。

<Image src='https://images.tuyacn.com/content-platform/hestia/1728295132fbcc3e947bd.jpg'/>

### 调试开发版和体验版

一些线上问题需要在真机中进行调试或日志输出，为方便查看前端日志的输出，App 端提供了 `调试模式`, 打开调试模式后面板界面中会显示 `vConsole` 按钮，点击后可打开手机端 `vConsole`界面查看日志输出。

调用 [changeDebugMode](/cn/miniapp/develop/ray/api/other/changeDebugMode), 开启 app 的调试模式，注意请勿在线上环境开启。

<div>
<Image src='/images/quick-start/vConsole1.jpeg' width="200px" />
<Image src='/images/quick-start/vConsole2.jpeg' width="200px"  />
</div>

## 五、体验测试

### 上传代码

1. 点击 Tuya MiniApp IDE 右上方的 **上传源码** 按钮，并填入对应版本号和备注后，本地代码将会上传至云端。

<Image src='https://images.tuyacn.com/fe-static/docs/img/63d4bfbc-1830-4f9f-b9fc-9eeb43d2e143.png'/>

### 完善信息

1. 在上传代码之后，我们需要保证当前面板小程序的一些基础及配置信息完善。进入 [小程序开发平台](https://platform.tuya.com/miniapp/)，并进入对应面板小程序的详情页。

2. 进入基础设置区块，根据表单项，填入 **小程序头像**、**小程序名称** 等基础信息，并填入 **中英文展示名称** 及 **中英文预览图** 这类涂鸦开发者平台展示用的信息，如下图所示。

<Image src='https://images.tuyacn.com/content-platform/hestia/16670532984589cd53f23.jpg'/>

### 设为体验版

1. 进入 **版本管理** 区块，找到此前上传的版本。

2. 单击 **设为体验版**，并单击 **确定** 即可。此时，该版本号会出现 **体验二维码** 按钮。此时先不要着急，我们需要先添加白名单。

<Image src='https://images.tuyacn.com/content-platform/hestia/16670545776043f922a54.jpg'/>

### 添加白名单

进入 **白名单** 区块，单击 **添加** 按钮，根据出现的表单信息配置好对应的 **App**、**App 账号**、**备注** 即可。

<Image src='https://images.tuyacn.com/content-platform/hestia/16670546019339259b468.jpg'/>

### 扫码测试

1. 最后我们回到 **版本管理** 区块，找到该版本号，单击 **体验二维码**。

2. 找到需要进行测试的设备 ID，并填入即可。注意 **真实设备** 和 **虚拟设备** 选择对应的下拉框进行区分选择。

   > 可通过面板工具中的设备信息区块获取设备 ID。

<Image src='https://images.tuyacn.com/content-platform/hestia/17282956667b70fe7c1ae.jpg'/>

3. 填入信息后，使用已添加过白名单的智能生活 App 账号进行扫码，即可完成体验测试。注意，当前虚拟或真实设备必须在当前 App 扫码的家庭下存在，才可正常进入该设备的面板。

## 六、审核上线

### 提交审核

1. 进入 [涂鸦小程序 开发者平台](https://platform.tuya.com/miniapp)，单击所需要上传的小程序，跳转至 **版本管理** 版块。

2. 在 **开发版本** 页签下，找到对应版本，单击 **提交审核**。

### 发布上线

1. 提交审核后，可在 **审核版本** 看到提交版本的审核状态。

2. 版本审核通过后，在 **线上版本** 看到待上线的版本。您可以通过 **暂停服务**、**启用服务** 按钮切换该版本小程序上下线状态。

### 关联产品

1. 在审核通过、发布上线后，回到 [涂鸦开发者平台](https://platform.tuya.com/)。

2. 找到需要更换为面板小程序的产品，在产品开发的 **02 设备交互** 步骤中，单击 **重选面板** 按钮。

<Image src='https://images.tuyacn.com/content-platform/hestia/17282959482bd2546f0df.jpg'/>

3. 选择 **自定义面板** 区域，可以发现之前刚发布的面板小程序可供选择。鼠标悬浮在该面板小程序上，单击出现的 **选择** 按钮，即可完成关联产品。

<Image src='https://images.tuyacn.com/content-platform/hestia/16670555280747fea8dec.jpg'/>

### 回归验收

1. 最后，回到 **02 设备交互** 步骤，通过智能生活 App 扫码添加虚拟设备。

2. 此时，去掉白名单或者通过其他非白名单账号访问该产品对应的虚拟设备或配网生成的真实设备，均可访问到之前发布的面板小程序。

## 七、常见问题

### 输入 `nvm -v` 时，为什么报错 `nvm: command not found`？

可能的原因是 NVM 所在的路径未设置为环境变量，您可以参照下述步骤设置环境变量：

1. 打开终端。

2. 输入`cd ~ `，进入当前用户的 Home 目录。

3. 输入以下命令，打开配置文件。
   - Window 系统

     ```shell
     open .bash_profile
     ```

   - macOS 系统

     ```shell
     open .bashrc
     ```

4. 在配置文件中，复制以下代码后，保存文件。

   ```shell
   export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
   ```

5. 输入 `source .bash_profile` 或 `source .bashrc`，重新加载配置文件。

6. 输入 `nvm -v`，查看 NVM 版本，验证是否安装成功。

如需了解更多 nvm 官方的解决方案，可参考 [NVM#Additional Notes](https://github.com/nvm-sh/nvm#additional-notes)