miot-plugin-sdk 0.61.1 跨平台开发环境深度配置指南1. 环境准备Windows与Mac双平台差异处理开发米家插件前需要根据操作系统选择不同的配置策略。Windows平台对Android开发更友好而Mac平台则可同时进行iOS和Android开发。以下是核心工具链要求工具/组件Windows要求Mac要求备注Node.js≥14.x (推荐16.x LTS)≥14.x (推荐16.x LTS)避免使用奇数版本JDKAzul Zulu JDK 11Azul Zulu JDK 11禁用系统自带OpenJDKPython3.8.x (添加到PATH)系统自带2.73.8双版本需配置python3别名Android StudioArctic Fox 2020.3.1Arctic Fox 2020.3.1统一版本避免兼容问题Git2.352.35需配置SSH密钥Windows特别配置# 管理员权限执行 Set-ExecutionPolicy RemoteSigned npm install -g windows-build-toolsMac特别配置brew install watchman sudo xcode-select --install环境验证命令node -v javac -version python --version2. SDK获取与网络优化方案2.1 多源获取SDK推荐通过Git克隆官方仓库git clone https://github.com/MiEcosystem/miot-plugin-sdk.git --depth1 cd miot-plugin-sdk若遇到网络问题可通过以下方式解决镜像加速推荐国内用户npm config set registry https://registry.npmmirror.com npm config set disturl https://npmmirror.com/dist离线包方案从CDN下载miot-plugin-sdk-v0.61.1-offline.zip解压后执行npm install --offline2.2 依赖安装异常处理常见错误及解决方案错误类型解决方案ECONNREFUSED切换镜像源或使用npm install --prefer-offlinePython版本冲突Windowsnpm config set python python3Macexport PYTHONpython3fsevents警告添加--no-optional参数或执行npm install fseventslatest -f3. 项目创建与模板选择3.1 创建命令详解npm run create com.yourcompany.product.model -type [template]模板类型对比模板类型适用场景包含基础功能empty完全自定义开发空白RN环境common标准WiFi设备状态管理定时功能ble蓝牙设备BLE连接管理器特征值读写mesh蓝牙Mesh/WiFi双模设备组网协议场景联动创建示例# 创建窗帘控制器项目 npm run create com.xiaomi.curtain.mtk1 -type ble3.2 项目结构解析miot-plugin-sdk ├── projects │ └── com.xiaomi.curtain.mtk1 │ ├── android # 原生代码目录 │ ├── ios # iOS原生代码(Mac可见) │ ├── resources # 静态资源 │ ├── package.json # 项目依赖 │ └── src │ ├── components # 公共组件 │ └── pages # 业务页面 └── scripts └── build.js # 编译脚本4. 调试环境全链路配置4.1 调试APP获取下载专用调试包curl -O https://cdn.mijia.com/mi-home-debug-5.5.50.apk禁用应用商店自动更新4.2 设备绑定流程启动调试服务npm start com.xiaomi.curtain.mtk1手机端操作路径米家APP → 我的 → 开发者选项 → 开启调试模式 → 添加Package/Model局域网调试要点确保电脑关闭防火墙使用ipconfig / ifconfig获取本机IP手机与电脑需同网段建议5GHz频段4.3 常见调试问题排查现象检查点解决方案二维码扫描失败8081端口占用lsof -i :8081 kill -9 PIDAPP白屏Metro服务日志清除APP缓存并重启服务设备未响应蓝牙权限配置检查AndroidManifest.xml热更新失效Hermes引擎兼容性禁用Hermes或清理缓存5. 进阶配置与性能优化5.1 自定义镜像方案对于企业级开发建议搭建私有npm仓库# Dockerfile示例 FROM verdaccio/verdaccio COPY config.yaml /verdaccio/conf/ EXPOSE 4873配置项目使用私有源npm config set registry http://your-private-registry:48735.2 编译速度优化开启Gradle缓存// android/gradle.properties org.gradle.cachingtrue org.gradle.paralleltrue使用Daemon模式./gradlew --daemon assembleDebug5.3 多设备联调技巧通过ADB实现多设备部署adb devices | grep device | awk {print $1} | xargs -I {} adb -s {} install app-debug.apk真机调试建议小米手机需开启USB调试连续点击MIUI版本号iOS设备需配置开发者证书使用react-native-log-ios查看详细日志6. 版本管理与兼容性6.1 SDK版本矩阵RN版本miot-plugin-sdk支持周期主要特性0.61.x0.6.x2023-2024基础蓝牙Mesh支持0.64.x0.7.x2024-2025新架构TurboModules0.68.x0.8.x2025并发渲染支持6.2 降级方案当需要兼容旧版APP时npm install miot-plugin-sdk0.5.4 --save-exact注意降级后需清理node_modules和android/build目录7. 开发资源推荐7.1 实用工具集调试工具React Native DebuggerFlipper 插件体系UI组件库npm install miot/ui-kit --registry https://npm.pkg.github.com7.2 官方资源小米IoT开发者平台API参考文档
miot-plugin-sdk 0.61.1 环境搭建：Windows/Mac 双平台 5 步配置与常见网络问题解决
发布时间：2026/7/12 6:19:19
miot-plugin-sdk 0.61.1 跨平台开发环境深度配置指南1. 环境准备Windows与Mac双平台差异处理开发米家插件前需要根据操作系统选择不同的配置策略。Windows平台对Android开发更友好而Mac平台则可同时进行iOS和Android开发。以下是核心工具链要求工具/组件Windows要求Mac要求备注Node.js≥14.x (推荐16.x LTS)≥14.x (推荐16.x LTS)避免使用奇数版本JDKAzul Zulu JDK 11Azul Zulu JDK 11禁用系统自带OpenJDKPython3.8.x (添加到PATH)系统自带2.73.8双版本需配置python3别名Android StudioArctic Fox 2020.3.1Arctic Fox 2020.3.1统一版本避免兼容问题Git2.352.35需配置SSH密钥Windows特别配置# 管理员权限执行 Set-ExecutionPolicy RemoteSigned npm install -g windows-build-toolsMac特别配置brew install watchman sudo xcode-select --install环境验证命令node -v javac -version python --version2. SDK获取与网络优化方案2.1 多源获取SDK推荐通过Git克隆官方仓库git clone https://github.com/MiEcosystem/miot-plugin-sdk.git --depth1 cd miot-plugin-sdk若遇到网络问题可通过以下方式解决镜像加速推荐国内用户npm config set registry https://registry.npmmirror.com npm config set disturl https://npmmirror.com/dist离线包方案从CDN下载miot-plugin-sdk-v0.61.1-offline.zip解压后执行npm install --offline2.2 依赖安装异常处理常见错误及解决方案错误类型解决方案ECONNREFUSED切换镜像源或使用npm install --prefer-offlinePython版本冲突Windowsnpm config set python python3Macexport PYTHONpython3fsevents警告添加--no-optional参数或执行npm install fseventslatest -f3. 项目创建与模板选择3.1 创建命令详解npm run create com.yourcompany.product.model -type [template]模板类型对比模板类型适用场景包含基础功能empty完全自定义开发空白RN环境common标准WiFi设备状态管理定时功能ble蓝牙设备BLE连接管理器特征值读写mesh蓝牙Mesh/WiFi双模设备组网协议场景联动创建示例# 创建窗帘控制器项目 npm run create com.xiaomi.curtain.mtk1 -type ble3.2 项目结构解析miot-plugin-sdk ├── projects │ └── com.xiaomi.curtain.mtk1 │ ├── android # 原生代码目录 │ ├── ios # iOS原生代码(Mac可见) │ ├── resources # 静态资源 │ ├── package.json # 项目依赖 │ └── src │ ├── components # 公共组件 │ └── pages # 业务页面 └── scripts └── build.js # 编译脚本4. 调试环境全链路配置4.1 调试APP获取下载专用调试包curl -O https://cdn.mijia.com/mi-home-debug-5.5.50.apk禁用应用商店自动更新4.2 设备绑定流程启动调试服务npm start com.xiaomi.curtain.mtk1手机端操作路径米家APP → 我的 → 开发者选项 → 开启调试模式 → 添加Package/Model局域网调试要点确保电脑关闭防火墙使用ipconfig / ifconfig获取本机IP手机与电脑需同网段建议5GHz频段4.3 常见调试问题排查现象检查点解决方案二维码扫描失败8081端口占用lsof -i :8081 kill -9 PIDAPP白屏Metro服务日志清除APP缓存并重启服务设备未响应蓝牙权限配置检查AndroidManifest.xml热更新失效Hermes引擎兼容性禁用Hermes或清理缓存5. 进阶配置与性能优化5.1 自定义镜像方案对于企业级开发建议搭建私有npm仓库# Dockerfile示例 FROM verdaccio/verdaccio COPY config.yaml /verdaccio/conf/ EXPOSE 4873配置项目使用私有源npm config set registry http://your-private-registry:48735.2 编译速度优化开启Gradle缓存// android/gradle.properties org.gradle.cachingtrue org.gradle.paralleltrue使用Daemon模式./gradlew --daemon assembleDebug5.3 多设备联调技巧通过ADB实现多设备部署adb devices | grep device | awk {print $1} | xargs -I {} adb -s {} install app-debug.apk真机调试建议小米手机需开启USB调试连续点击MIUI版本号iOS设备需配置开发者证书使用react-native-log-ios查看详细日志6. 版本管理与兼容性6.1 SDK版本矩阵RN版本miot-plugin-sdk支持周期主要特性0.61.x0.6.x2023-2024基础蓝牙Mesh支持0.64.x0.7.x2024-2025新架构TurboModules0.68.x0.8.x2025并发渲染支持6.2 降级方案当需要兼容旧版APP时npm install miot-plugin-sdk0.5.4 --save-exact注意降级后需清理node_modules和android/build目录7. 开发资源推荐7.1 实用工具集调试工具React Native DebuggerFlipper 插件体系UI组件库npm install miot/ui-kit --registry https://npm.pkg.github.com7.2 官方资源小米IoT开发者平台API参考文档
