# net.listen

## 功能

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

## 语法

```bt
net.listen(config)
```

## 参数

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

## 公共配置字段

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

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

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

| type | 专属文档 | 说明 |
| ------ | ------ | ------ |
| web | [Web 服务](/zh-hans/docs/net/web) | 站点 sites、静态目录、上传临时目录、TLS 等 Web 服务配置。 |
| tcp | [TCP 通信](/zh-hans/docs/net/tcp) | TCP 服务端事件回调和客户端读写。 |
| udp | [UDP 通信](/zh-hans/docs/net/udp) | UDP 消息回调和发送目标地址。 |
| ws | [WebSocket 通信](/zh-hans/docs/net/websocket) | WebSocket 路由、连接回调和消息回调。 |

## 返回值

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

## 服务句柄公共字段

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

## 服务句柄公共方法

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

## 示例

```bt
// 监听本机随机空闲端口；真实端口可通过 server.addr 读取。
server = net.listen({
    type: 'tcp',
    bind: '127.0.0.1:0'
})
result = server.addr
server.close()

// 输出示例：127.0.0.1:52341
print result
```

## 注意事项

- 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](/zh-hans/docs/bt/stats) 的 net 配置说明。