js怎样操作Web Serial API实现串口设备通信的5个基础步骤

Web Serial API是浏览器提供的原生接口，支持网页直接和用户设备的串口进行通信，无需依赖第三方插件，适合需要前端和硬件设备交互的场景。使用该API实现串口通信需要遵循固定的流程，核心分为5个基础步骤。

第一步：请求用户授权并选择串口设备

浏览器出于安全考虑，不允许网页直接访问所有串口设备，需要先向用户发起授权请求，让用户选择要连接的串口。这一步通过navigator.serial.requestPort()方法实现，该方法会返回用户选择的SerialPort对象实例。

// 请求用户选择串口设备
async function requestSerialPort() {
  try {
    // 调用requestPort弹出设备选择弹窗，用户选择后返回端口实例
    const port = await navigator.serial.requestPort();
    console.log('已选择串口:', port);
    return port;
  } catch (error) {
    // 用户取消选择或者浏览器不支持时会抛出错误
    console.error('请求串口失败:', error);
    return null;
  }
}

第二步：打开串口连接并配置参数

获取到SerialPort实例后，需要先打开连接，同时配置串口的通信参数，比如波特率、数据位、停止位、校验位等，这些参数需要和连接的硬件设备保持一致，否则会出现通信异常。

// 打开串口并配置参数
async function openSerialPort(port) {
  if (!port) {
    console.error('未获取到有效的串口实例');
    return false;
  }
  try {
    // 打开串口，配置波特率为9600，数据位8，停止位1，无校验
    await port.open({
      baudRate: 9600,
      dataBits: 8,
      stopBits: 1,
      parity: 'none'
    });
    console.log('串口已成功打开');
    return true;
  } catch (error) {
    console.error('打开串口失败:', error);
    return false;
  }
}

第三步：设置数据读取流监听接收数据

串口连接打开后，需要监听设备发送过来的数据。Web Serial API使用流（Stream）的方式处理数据，我们需要获取串口的只读流，然后通过reader读取数据，通常会在循环中持续读取，直到连接关闭。

// 监听串口接收数据
async function readSerialData(port) {
  // 获取串口的只读流
  const reader = port.readable.getReader();
  try {
    // 循环读取数据
    while (true) {
      // 读取数据，value是Uint8Array类型的字节数组
      const { value, done } = await reader.read();
      if (done) {
        // 流被关闭时退出循环
        reader.releaseLock();
        break;
      }
      // 将字节数组转换为字符串，根据实际设备编码调整
      const receivedData = new TextDecoder().decode(value);
      console.log('接收到串口数据:', receivedData);
    }
  } catch (error) {
    console.error('读取串口数据失败:', error);
  } finally {
    // 释放reader锁
    reader.releaseLock();
  }
}

第四步：通过写入流发送数据到设备

向串口设备发送数据时，需要获取串口的只写流，创建写入器writer，将需要发送的数据转换为字节数组后写入流中，发送完成后需要释放写入器的锁。

// 向串口发送数据
async function writeSerialData(port, data) {
  // 获取串口的只写流
  const writer = port.writable.getWriter();
  try {
    // 将字符串转换为Uint8Array字节数组，根据实际需求调整编码
    const dataArray = new TextEncoder().encode(data);
    // 写入数据
    await writer.write(dataArray);
    console.log('数据已发送到串口:', data);
    return true;
  } catch (error) {
    console.error('发送串口数据失败:', error);
    return false;
  } finally {
    // 释放writer锁
    writer.releaseLock();
  }
}

第五步：关闭串口连接释放资源

通信完成后，需要及时关闭串口连接，释放相关的资源，避免占用设备导致其他程序无法访问。关闭连接前需要先停止数据读取，再调用port.close()方法。

// 关闭串口连接
async function closeSerialPort(port) {
  if (!port || !port.readable || !port.writable) {
    console.log('串口未打开或已关闭');
    return;
  }
  try {
    // 关闭串口连接
    await port.close();
    console.log('串口已成功关闭');
  } catch (error) {
    console.error('关闭串口失败:', error);
  }
}

完整流程示例

将上面的5个步骤组合起来，就可以实现完整的串口通信流程，以下是完整的调用示例：

// 完整串口通信流程示例
async function serialCommunicationDemo() {
  // 步骤1：请求串口
  const port = await requestSerialPort();
  if (!port) return;

  // 步骤2：打开串口
  const isOpen = await openSerialPort(port);
  if (!isOpen) return;

  // 步骤3：启动数据读取（放在异步函数中避免阻塞）
  readSerialData(port);

  // 步骤4：发送测试数据
  await writeSerialData(port, 'Hello Serial Device');

  // 模拟通信一段时间后关闭连接
  setTimeout(async () => {
    // 步骤5：关闭串口
    await closeSerialPort(port);
  }, 5000);
}

// 调用示例
serialCommunicationDemo();

注意事项

• Web Serial API仅支持在HTTPS环境或者localhost本地环境中使用，普通HTTP页面无法调用该接口。
• 不同浏览器的支持程度不同，使用前可以通过'serial' in navigator判断当前浏览器是否支持该API。
• 串口参数需要和硬件设备的配置完全一致，否则会出现数据乱码或者无法通信的问题。
• 读写流操作都需要使用异步函数，避免阻塞主线程导致页面卡顿。

Web_Serial_APIjs串口通信串口设备连接前端硬件交互SerialPort修改时间：2026-07-04 16:27:26