欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在进行 OpenHarmony 应用开发时，有时我们需要在 App 内部启动一个本地服务器，例如：

• 为内嵌的 Webview 提供本地资源访问。
• 在局域网内进行设备间的数据同步（如投屏、文件传输）。
• 进行自动化集成测试。

通常的 HttpServer.bind 只能绑定一个地址（要么是 localhost，要么是具体的 IP）。而 http_multi_server 允许你一次性绑定多个地址，让你的鸿蒙 App 同时在本地回环和局域网 IP 上提供服务。

一、核心原理解析

它实际上是一个 HttpServer 的聚合器。它通过同时启动多个底层的 Dart HttpServer 实例，并将它们分发的请求流（Request Stream）进行合并。

二、核心 API 实战

2.1 绑定所有可用地址

这是最通用的用法，会自动绑定 IPv4 和 IPv6 的所有可用环回或全局地址。

import 'package:http_multi_server/http_multi_server.dart';

void startServer() async {
  // 💡 在 8080 端口绑定所有可用地址
  final server = await HttpMultiServer.bind('any', 8080);
  
  print('服务器已启动，正在监听：${server.address}');
  
  server.listen((request) {
    request.response
      ..write('来自鸿蒙本地服务器的消息')
      ..close();
  });
}

2.2 绑定特定列表

final server = await HttpMultiServer.bind([
  InternetAddress.loopbackIPv4,
  '192.168.31.100', // 💡 鸿蒙真机的局域网 IP
], 8081);

2.3 获取实际监听地址

由于是多地址绑定，你可以通过属性查看具体详情。

print('连接地址列表: ${server.connections}');

三、OpenHarmony 平台适配

3.1 端口占用处理

在鸿蒙设备上启动服务器前，请务必检查端口是否被系统或其他应用占用。建议使用随机端口（端口号设为 0）。

3.2 局域网访问权限

💡 注意：如果希望局域网内的其他设备（如 PC 浏览器）访问鸿蒙手机上的该服务，除了 ohos.permission.INTERNET，通常还需要确保手机和电脑在同一个 WiFi 下，且关闭了 AP 隔离。

3.3 性能与能耗建议

在鸿蒙系统中，后台运行的 HTTP 服务可能会被系统挂起。如果用于长时间的文件传输，建议配合鸿蒙的“持续任务”申请相关的保活权限。

四、完整实战示例：鸿蒙企业级多端口分发中心

本示例展示了如何结合 shelf 框架，在鸿蒙设备上构建一个结构化的多址 HTTP 服务。

import 'package:http_multi_server/http_multi_server.dart';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as shelf_io;

void setupOhosService() async {
  // 1. 💡 绑定所有地址 (any) 在 9000 端口
  final multiServer = await HttpMultiServer.bind('any', 9000);
  
  // 2. 💡 路由处理逻辑 (包含路径过滤与 HTML 返回)
  Response _handler(Request request) {
    // 过滤浏览器自动发起的图标请求
    if (request.url.path == 'favicon.ico') return Response.notFound(null);

    return Response.ok(
      '<h1>🚀 鸿蒙企业中心</h1><p>已成功处理来自 ${request.url.path} 的请求</p>',
      headers: {'content-type': 'text/html; charset=utf-8'},
    );
  }

  // 3. 💡 集成 Shelf 管道与多址监听器
  var pipeline = const Pipeline()
      .addMiddleware(logRequests())
      .addHandler(_handler);

  // 💡 将 multiServer 实例传给 shelf_io 进行分发
  shelf_io.serveRequests(multiServer, pipeline);
  print("✅ 服务已上线: http://localhost:9000");
}

五、总结

http_multi_server 为 OpenHarmony 开发者处理复杂的网络拓扑提供了极大的便利。它屏蔽了 IPv4/IPv6 以及不同网络接口的底层差异，让你能通过同一套逻辑实现“内外网同时监听”。无论是做本地调试工具还是跨设备分发功能，它都是构建鸿蒙嵌入式服务的标准底板。