基于 matter.js 的 Matter 开发指南，覆盖 Node.js 控制器、浏览器代理和设备桥接。
matter.js 是 Matter 协议的纯 TypeScript 实现，由 Open Home Foundation 维护，可用于构建控制器、虚拟设备和桥接器。Home Assistant 2026.7 已将其作为 Matter 控制器投入生产。注意：matter.js 目前尚未获得 CSA 官方认证，认证工作仍在推进中。
关键点：浏览器无法直接与 Matter 设备通信（因为 Matter 使用 UDP 而浏览器不支持原始 UDP 套接字）。实际方案是 Node.js 服务端运行 matter.js，浏览器通过 WebSocket 代理控制。
matter.js 生态中的核心包和使用模式：
| 包名 | 用途 | 运行环境 |
|---|---|---|
| @matter/main | matter.js 主入口，Behavior API | Node.js / Bun |
| @matter/nodejs | Node.js 平台适配器（UDP / mDNS / BLE） | Node.js |
| @matter/node | ServerNode / Endpoint / Behavior | Node.js |
| @matter-server/ws-client | 浏览器端 WebSocket 客户端 | 浏览器 / Node.js |
| @matter-server/ws-controller | 服务端 Matter 控制器 | Node.js |
| matterbridge | 基于插件的 Matter 桥接框架 | Node.js |
浏览器的安全模型从根本上阻止了 Matter 协议的直接运行：
Matter 运行在 UDP 5540 端口上，浏览器无法访问原始 UDP 套接字。这是安全模型约束，不是缺少 API。
Matter 使用组播 DNS 发现设备，浏览器无法发送或接收组播 UDP 包。
Web Bluetooth 需要用户手势弹出设备选择器，无法实现 Matter 所需的静默 BLE 扫描和 PASE 会话。
浏览器没有 Thread 网络 API，无法配置 Thread 设备凭据。
matterjs-server 提供了经过生产验证的浏览器接入方案。Node.js 服务端持有完整的 Matter 控制器，浏览器通过 WebSocket 远程操作。
import { MatterClient } from "@matter-server/ws-client";
// 连接到本地 matterjs-server
const client = new MatterClient("ws://localhost:5580/ws");
await client.startListening();
// 查看已配网的设备
const nodes = client.nodes;
// 发送设备命令：切换灯光 (endpoint 1, cluster 6 = OnOff)
await client.deviceCommand(nodeId, 1, 6, "toggle");
// 监听设备状态变化
client.addEventListener("nodes_changed", (event) => {
console.log("状态变化:", event);
});在 Node.js 环境中，matter.js 可以直接运行完整的 Matter 控制器，无需任何代理层：
import { CommissioningController } from "@matter/main";
import { OnOff } from "@matter/main/clusters";
// 创建并启动控制器
const controller = new CommissioningController({
environment: { environment, id: "MyController" },
autoConnect: true,
});
await controller.start();
// 获取已配网设备的端点
const node = controller.getNode(nodeId);
const endpoint = node.getEndpoint(1);
// 通过 Cluster API 控制设备
const onOffCluster = endpoint.getClusterClient(OnOff.Cluster);
await onOffCluster.toggle();matterjs-server 在配网后已经把设备的全部属性读好了，浏览器端直接从节点数据里按 端点/Cluster/属性 取值即可。这份数据粘进 JSON 解析器 就能看到整理好的设备画像；字段含义见 概念总览 · 配网后怎么读出设备能力。
import { MatterClient } from "@matter-server/ws-client";
const client = new MatterClient("ws://localhost:5580/ws");
await client.startListening();
// 服务端在配网后会对设备做一次通配读取，节点数据里就是全部原始属性
// 键名为 "端点/Cluster/属性"（十进制），与 Home Assistant 诊断导出格式相同
const attrs = client.nodes[nodeId].attributes;
const endpoints = attrs["0/29/3"]; // Descriptor.PartsList → [1]
for (const ep of endpoints) {
const types = attrs[`${ep}/29/0`]; // DeviceTypeList → [{ "0": 10, "1": 3 }] 10 = 0x000A 门锁
const servers = attrs[`${ep}/29/1`]; // ServerList → [3, 29, 47, 257]
console.log(ep, types, servers);
}
const vendorName = attrs["0/40/1"]; // BasicInformation.VendorName
const lockFeatures = attrs["1/257/65532"]; // DoorLock.FeatureMap