# @0x5e/homebridge-tuya-platform 中文文档 规范地址：https://npmcn.com/package/%400x5e/homebridge-tuya-platform/ 版本：1\.7\.0-beta\.58 npm 元数据更新时间：2026-04-16T15:43:50.364Z 中文译文更新时间：2026-11-07T01:43:30.677Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%400x5e/homebridge-tuya-platform 原文对照：https://npmcn.com/package/%400x5e/homebridge-tuya-platform/?lang=original 项目主页：https://github.com/0x5e/homebridge-tuya-platform#readme 源码仓库：https://github.com/0x5e/homebridge-tuya-platform ## 关键信息（来自 npm 元数据） - 包体积（解压后）：738 kB，326 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=14\.18\.1 - 运行依赖：10 个 - 首次发布：2022-10-19T10:22:37.729Z - 最新版本发布：2026-04-16T15:43:50.241Z - 近 30 天下载量：2098（2026-10-04 至 2026-11-02，npm 官方下载统计） - 已发布版本数：101（近 12 个月 4 个） ## 中文简介 叉子版官方图亚家桥插件. 带来一串bug修复和新设备支持. ## 安装 ```sh npm install @0x5e/homebridge-tuya-platform ``` 也可以使用：`pnpm add @0x5e/homebridge-tuya-platform`、`yarn add @0x5e/homebridge-tuya-platform`、`bun add @0x5e/homebridge-tuya-platform` ## README # @0x5e/homebridge-tuya-平台 [![npm](https://badgen.net/npm/v/@0x5e/homebridge-tuya-platform)](https://npmjs.com/package/@0x5e/homebridge-tuya-platform) [![npm](https://badgen.net/npm/dt/@0x5e/homebridge-tuya-platform)](https://npmjs.com/package/@0x5e/homebridge-tuya-platform) [![mit-license](https://badgen.net/npm/license/@0x5e/homebridge-tuya-platform)](https://github.com/0x5e/homebridge-tuya-platform/blob/main/LICENSE) [![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins) [![Build and Lint](https://github.com/0x5e/homebridge-tuya-platform/actions/workflows/build.yml/badge.svg)](https://github.com/0x5e/homebridge-tuya-platform/actions/workflows/build.yml) [![join-discord](https://badgen.net/badge/icon/discord?icon=discord&label=homebridge/tuya)](https://discord.gg/homebridge-432663330281226270) 叉口版为Tuya Homebridge官方插件,以修复bug和添加新设备支持为主. ⚠️**2024.1.14的最新情况:** 感谢大家关注这个项目。 越来越多的"出问题装置",通过制造有错误的定义(反倒了0%-100%的状态,错误的范围,错误的单位,.). 一个接一个地支持他们 真的很贵 我以后不会支持他们 请自己解决 PR仍然是受欢迎的,而bug将会被聚焦. 再次感谢:) ## 特征 - 优化并改进了代码,以提高可读性和可维护性. - 加强稳定性. - 减少重复代码 . - API 错误减少 . - 新附属类别的开发费用较低. - 支持图亚·斯克内斯(Tap-to-Run). - 包括能够覆盖设备配置,从而能够支持"非标准"的DP. - 支持超过60+设备类别,包括大多数光,开关,传感器,相机,锁,IR遥控等. ## 支持的 Tuya 设备 见 [支援 DEVICES.md](https://npmcn.com/package/%400x5e/homebridge-tuya-platform/SUPPORTED_DEVICES.md) ## 更改日志 见 [变动情况](https://npmcn.com/package/%400x5e/homebridge-tuya-platform/CHANGELOG.md) ## 安装 使用此插件之前, 请确定是否卸载 `homebridge-tuya-platform` 首先,这两个插件不能同时运行。 然而,配置文件是相容的,所以不需要删除. #### 家用桥网络用户 转到插件页面, 查找 `@0x5e/homebridge-tuya-platform` 并安装它. #### 家桥命令行用户 在终端中运行以下命令 : ``` npm install @0x5e/homebridge-tuya-platform ``` ## 配置 有两类项目: `Custom` 财务报告和审定财务报表 `Smart Home`。 。 。 . 他们之间的区别是: - 这个 `Custom` 项目从项目资产中提取设备. - 这个 `Smart Home` 项目从Tuya应用程序中的用户家提取设备. 如果你是个人用户,不确定选择哪一个,请使用 `Smart Home` 项目. 在配置之前,您必须前往 [Tuya IoT 平台](https://iot.tuya.com/)数字 : - 创建一个云开发项目,并选择您的应用账户所在的数据中心 。 见 [OEM App账户和数据中心之间的绘图](https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb) - 转到 `Project Page` > 翻译: `Devices Panel` > 翻译: `Link Tuya App Account`,链接您的应用账户. - 转到 `Project Page` > 翻译: `Service API` > 翻译: `Go to Authorize`,并订阅下列API(可免费试用): - 授权托肯管理 - 设备状态通知 - IoT 核心 - IOT 视频活流(用于相机) - 工业项目客户服务处 `Custom` 项目) - IR 控制中心开放服务(用于IR设备) - 智能家庭场景链接(用于场景) - 智能锁定打开服务( 用于锁定设备) - **请记住每六个月将API试验期延长一次 [Tuya IoT平台 > Cloud > Cloud 服务 > IoT Core](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014&id=p1668587814138nv4h3n&abilityAuth=0&tab=1) (第一次订阅只给你一个月).** #### “海关”项目 - `platform` - 说吧 **所需经费** :必须是"TuyaPlatform". - `options.projectType` - 说吧 **所需经费** : 必须是"1" - `options.endpoint` - 说吧 **所需经费** : 端点 URL 从 [API 参考 > 终点](https://developer.tuya.com/en/docs/iot/api-request?id=Ka4a8uuo1j4t4#title-1-Endpoints) 页:1. - `options.accessId` - 说吧 **所需经费** : 从 [Tuya IoT 平台 > 云开发](https://iot.tuya.com/cloud)。 。 。 . - `options.accessKey` - 说吧 **所需经费** : 从 [Tuya IoT 平台 > 云开发](https://iot.tuya.com/cloud)。 。 。 . - `options.debug` - 说吧 **选项**:包括家园桥日志中的调试输出. (默认 : `false`(中文(简体) ) - `options.debugLevel` - 说吧 **选项**: 带有逗号的可选字符串列表 `,`。 。 。 . `api` 代表 HTTP API 日志, `mqtt` 代表MQTT日志,设备标识代表设备日志. 如果空白, 所有日志都会输出 . #### "闪闪发光"项目 - `platform` - 说吧 **所需经费** :必须是"TuyaPlatform". - `options.projectType` - 说吧 **所需经费** :必须是"2". - `options.accessId` - 说吧 **所需经费** : 从 [Tuya IoT 平台 > 云开发](https://iot.tuya.com/cloud)。 。 。 . - `options.accessKey` - 说吧 **所需经费** : 从 [Tuya IoT 平台 > 云开发](https://iot.tuya.com/cloud)。 。 。 . - `options.countryCode` - 说吧 **所需经费** : 您开发商账户所在区域的数值国家代码. 您可以找到国家代码列表 [这里](https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb)。 。 。 . - `options.username` - 说吧 **所需经费** :移动应用(Tuya或SmartLife)账户的用户名. 不要使用Tuya IoT平台开发者用户名. - `options.password` - 说吧 **所需经费** :移动应用程序(Tuya或SmartLife)账户密码. MD5也提供有盐的密码,用于加强安全. 不要使用Tuya IoT平台开发者密码. - `options.appSchema` - 说吧 **所需经费** : app schema:为图亚智能App的"tuyaSmart",或为智能App的"智能生活". - `options.endpoint` - 说吧 **选项** : 端点 URL 可以从 [API 参考 > 终点](https://developer.tuya.com/en/docs/iot/api-request?id=Ka4a8uuo1j4t4#title-1-Endpoints) 表格基于所提供的国家代码。 只有遇到登录问题并需要指定账户位置的终点时,才手工设置此值. - `options.homeWhitelist` - 说吧 **选项**: 用于您想要白名单的家用ID的整数组。 如果提供,则只包括匹配家庭身份证的设备。 您可以在家园桥日志中找到家庭身份证. - `options.debug` - 说吧 **选项**:包括家园桥日志中的调试输出. (默认 : `false`(中文(简体) ) - `options.debugLevel` - 说吧 **选项**: 带有逗号的可选字符串列表 `,`。 。 。 . `api` 代表API和MQTT日志,设备ID代表特定设备日志. 如果空白, 所有日志都会输出 . #### 高级选项 见 [预选](https://npmcn.com/package/%400x5e/homebridge-tuya-platform/ADVANCED_OPTIONS.md) ## 限制 - **别忘了每6个月延长API的试用期. 也许你可以在日历中设置一个提醒.** - 对多个家用桥/家用助理实例不支持使用同一应用程序账户。 请为每个实例使用单独的应用账户 . - 该插件需要连接到Tuya Cloud的互联网,而不支持LAN协议. 见 [90号](https://github.com/0x5e/homebridge-tuya-platform/issues/90) 更多信息. ## 财务问题 #### 关于登录问题 对于大多数用户来说,你可以很容易地通过该程序找到您的应用账户的数据中心 [文档](https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb) 并没有任何问题地登录。 然而,对于一些用户来说,他们可能会遇到错误代码,如1106或2406. 如果你遇到这样的错误,那么你的数据中心和文档之间可能存在差异. 为确定数据中心,遵循这些步骤: 1. 打开应用程序并导航到"我 > 设置 > 网络诊断". 2. 开始诊断并选择"上载日志 > 复制日志到剪贴板". 3. 在任何地方粘贴日志并找到以"Region代码:"开头的行:. 4. 寻找以下代码:"AY"代表中国,"AZ"代表美国西部,"欧盟"代表中欧,"IN"代表印度. 然后在插件配置中手动指定终点 . #### 什么是"标准DP"和"非标准DP"? “Standard DP”是指Tuya IoT开发平台文档中指定的设备属性或功能 [Tuya IoT 开发平台文档 > Cloud Development > 标准指令集](https://developer.tuya.com/en/docs/iot/standarddescription?id=K9i5ql6waswzq)。 。 。 . 例如,灯泡应该有标准的DP代码: `switch_led` 和可选代码 `bright_value`编号 :`bright_value_v2` 以光泽发誓, `temp_value`编号 :`temp_value_v2` 颜色温度,和 `work_mode` 用于修改工作模式。 这些代码可参见上述文档. 如果你的灯泡可以在Tuya应用中调整,但不能与插件一起调整,它最有可能有"非标准DP" #### 此插件能支持“ 非标准 DP ” 吗 ? 对 该设备必须被列入支持列表并完成以下步骤后才能工作: 1 1. 更改 Tuya 平台上的设备控制模式 : - 转到 "[图亚平台云发展](https://iot.tuya.com/cloud/) >您的项目 > 设备 > 所有设备 > 按产品查看设备. - 查找与您设备相关的产品,单击"pencil"图标(Change Control Direction Mode). - ![image](https://user-images.githubusercontent.com/5144674/202967707-8b934e05-36d6-4b42-bb7b-87e5b24474c4.png) - 在"指令表"中,您可以看到云映射,并确定哪些DP代码缺失,需要稍后手动映射. - ![image](https://user-images.githubusercontent.com/5144674/202967528-4838f9a1-0547-4102-afbb-180dc9b198b1.png) - 选择“ DP 指令” 并保存 . 2. 覆盖设备计划, 查看 [预选](https://npmcn.com/package/%400x5e/homebridge-tuya-platform/ADVANCED_OPTIONS.md)。 。 。 . #### 当地支助 见 [90号](https://github.com/0x5e/homebridge-tuya-platform/issues/90)。 。 。 . 虽然这个插件现在还没有执行tuya本地协议,但将来仍然有可能. ## 解决问题 如果没有支持您的设备, 请遵循这些步骤来收集信息 . #### 1\. 获取设备信息 Homebridge成功出道后,设备信息列表会被保存到Homebridge的坚持道上. 您可以在家园桥日志中找到文件路径 : ``` [2022/11/3 18:37:43] [TuyaPlatform] Device list saved at /path/to/TuyaDeviceList.{uid}.json ``` **请确保删除敏感信息, 如 `ip`, (中文(简体) ), `lon`, (中文(简体) ), `lat`, (中文(简体) ), `local_key`,以及 `uid` 在提交文件之前.** #### 2\. 启用调试模式 在插件配置中添加调试选项, 然后重新启动 Homebridge . #### 3\. 收集日志 启用调试模式后,您现在可以接收 MQTT 日志 。 操作您的设备, 无论是在物理上还是通过 Tuya App , 接收这样的 MQTT 日志 : ``` [2022/12/8 12:51:59] [TuyaPlatform] [TuyaOpenMQ] onMessage: topic = cloud/token/in/xxx protocol = 4 message = { "dataId": "xxx", "devId": "xxx", "productKey": "xxx", "status": [ { "1": "double_click", "code": "switch1_value", "t": "1670475119766", "value": "double_click" } ] } ``` 如果您在控制设备时无法接收到任何 MQTT 日志,则可能意味着您的设备有"非标准 DP" . 通过提交设备信息JSON和MQTT日志,您可以帮助我们支持新的设备类别. ## 捐款 请看 [https://github.com/homebridge/homebridge-plugin-template#setup-development-environment 页面存档备份,存于互联网档案馆](https://github.com/homebridge/homebridge-plugin-template#setup-development-environment) 开发环境. 公关和问题受到欢迎. 谢谢你花时间利用这个项目 如果这能帮助你,就不要犹豫地给它一颗恒星 ## 常见问题 ### @0x5e/homebridge-tuya-platform 是什么？ 叉子版官方图亚家桥插件\. 带来一串bug修复和新设备支持\. ### 如何安装 @0x5e/homebridge-tuya-platform？ 在项目目录运行 npm install @0x5e/homebridge-tuya-platform，或使用 pnpm add / yarn add / bun add。 ### @0x5e/homebridge-tuya-platform 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @0x5e/homebridge-tuya-platform 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @0x5e/homebridge-tuya-platform 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=14\.18\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @0x5e/homebridge-tuya-platform 可以商用吗？ @0x5e/homebridge-tuya-platform 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @0x5e/homebridge-tuya-platform 的下载量有多少？ 根据 npm 官方下载统计，@0x5e/homebridge-tuya-platform 在 2026/10/04 – 2026/11/02 这 30 天内被下载 2,098 次，日均约 70 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @0x5e/homebridge-tuya-platform 还在维护吗？ 最新版本 1\.7\.0-beta\.58 发布于 2026/04/16（6 个月前）；至今共发布 101 个版本，其中过去 12 个月发布了 4 个；首次发布于 2022/10/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。