net.listen

net.listen

AI 原文

net.listen

功能

启动 Web、TCP、UDP 或 WebSocket 监听服务。

语法

参数

参数类型必填默认值说明
configObject是无监听配置对象。公共字段见下方，协议专属字段请查看对应协议文档。

公共配置字段

net.listen(config) 的所有监听类型都通过 type 选择协议，并通过 bind 指定监听地址。建议所有监听配置都显式写出 type 和 bind，便于代码、文档和 AI 工具稳定识别服务入口。

字段类型必填默认值说明
typeString是无监听协议类型。可选值为 web、tcp、udp、ws。
bindStringtcp/udp/ws 必填；web 建议填写web 默认为 0.0.0.0:8080监听地址，格式为 主机:端口，例如 127.0.0.1:9000、0.0.0.0:8080。端口写 0 时由操作系统分配空闲端口。
binaryBooltcp/udp/ws 可选false为 true 时，消息回调收到 Bytes；默认保持 String 兼容行为。

协议专属字段放在对应页面说明：

type专属文档说明
webWeb 服务站点 sites、静态目录、上传临时目录、TLS 等 Web 服务配置。
tcpTCP 通信TCP 服务端事件回调和客户端读写。
udpUDP 通信UDP 消息回调和发送目标地址。
wsWebSocket 通信WebSocket 路由、连接回调和消息回调。

返回值

类型说明
WebServer TcpServer UdpSocket WsServer按 type 返回对应服务句柄。

服务句柄公共字段

字段类型说明
addrString实际监听地址，格式通常为 host:port；bind 端口写 0 时可从这里读取系统分配后的端口。
typeString服务类型。Web 返回 web，TCP 返回 tcp，UDP 返回 udp，WebSocket 返回 ws。

服务句柄公共方法

方法返回值说明
close()Bool关闭监听服务或 socket，成功返回 true。

示例

注意事项

  • net.listen 短写等价于 net().listen。
  • bind 必须包含端口；缺少端口或端口无效会抛出错误。
  • 127.0.0.1 只允许本机访问，0.0.0.0 会监听所有网卡地址。
  • TCP、UDP、WebSocket 监听服务使用共享 Tokio runtime，后台事件通过有界队列投递到 VM。
  • TCP、UDP、WebSocket 二进制协议建议设置 binary: true，避免回调参数提前按字符串转换。
  • 网络事件队列和连接资源上限见 BT.stats 的 net 配置说明。