Android手机上跑的迷你Web服务器，开箱即用支持局域网访问

原创于 2026-06-13 04:36:07 发布 · 248 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#NanoHTTPD #Android Web服务器 #嵌入式HTTP服务

该文章已生成可运行项目，

本文还有配套的精品资源，点击获取

简介：在Android设备本地快速启动一个轻量HTTP服务，基于NanoHTTPD 2.2.0实现，纯Java编写，不依赖外部容器。支持自定义端口、绑定指定IP（如127.0.0.1或局域网IP）、处理GET/POST请求、返回静态HTML或JSON响应。项目已配置好Gradle依赖、ProGuard混淆规则和标准Android目录结构，主服务类AndroidWebServer可直接继承扩展。启动只需new一个实例并调用start()方法，停止时调用stop()。适合用于App内部调试接口、H5页面本地预览、局域网内共享小文件、IoT设备简易控制页、离线文档托管等场景。兼容Android 4.0+，内存占用低，无额外权限要求，集成进工具类App或开发辅助模块非常方便。README.md里写清了启动步骤、常见问题和注意事项。

1. 项目概述：为什么你需要一个“塞进口袋的Web服务器”

你有没有过这样的时刻：调试一个刚写好的H5页面，想在手机上实时预览效果，却卡在“怎么把本地HTML丢进Android浏览器里”这一步？或者手头有个IoT设备原型，需要临时搭个控制界面，但又不想折腾一台树莓派或云服务器？又或者，你在开发一款工具类App，突然发现——如果能让App自己变成一个HTTP服务端，直接响应局域网内其他设备（比如同事的笔记本、另一台测试机）发来的请求，那调试效率能翻倍，甚至能绕过复杂的跨域和证书问题？

这个项目就是为这些“就差一点点”的真实场景而生的。它不是一个玩具Demo，也不是需要你从零配置Tomcat或Nginx的重型方案；它是一段可直接编译、一键启动、开箱即用的嵌入式HTTP服务代码包，核心就靠一个叫 NanoHTTPD 的轻量级Java库（版本2.2.0），跑在Android设备上，不依赖任何外部Web容器，纯Java实现，连JNI都不用。

关键词里的“NanoHTTPD”不是随便贴的标签——它是整个项目的灵魂。NanoHTTPD的设计哲学就是“极简”：单个Java文件就能跑起来（虽然我们这里用了它的标准Maven模块），没有XML配置，没有Servlet容器生命周期管理，没有线程池参数调优的焦虑。它把HTTP协议栈最核心的部分（解析请求行、读取Header、处理Body、组装响应）封装成几个干净的回调方法，让你专注在“我到底想返回什么内容”这件事上。而“Android Web服务器”和“嵌入式HTTP服务”这两个词，则精准划定了它的能力边界：它不追求高并发、不支持WebSocket长连接、不内置HTTPS（除非你自己加SSLContext），但它能在Android 4.0+（API Level 14）的老设备上稳定运行，内存常驻占用通常压在2MB以内，启动耗时不到300ms。这意味着你可以把它当成一个“可插拔的模块”，集成进你的日志查看器、网络诊断工具、离线文档阅读器，甚至是一个给家人用的简易照片共享App里，完全不会拖慢主App的体验。

我第一次把它塞进一个内部调试工具时，最大的惊喜是——它真的不需要任何特殊权限。<uses-permission android:name="android.permission.INTERNET" /> 是唯一必需的声明，连ACCESS_NETWORK_STATE都只是用来做状态提示的可选项。这意味着你不用跟用户解释“为什么这个小工具要访问你的网络”，也不用担心在Android 10+的Scoped Storage下被权限策略卡住。它绑定的是设备自身的网络接口，当你在代码里指定bindAddress = "0.0.0.0"时，它会自动监听所有可用网卡（Wi-Fi、热点、甚至USB网络共享），局域网内的其他设备只要知道你的手机IP（比如192.168.1.105:8080），就能像访问普通网站一样打开你的页面或调用你的API。这种“去中心化”的调试方式，彻底改变了我们团队的前后端联调节奏：前端改完一行CSS，adb push到手机指定目录，刷新浏览器即可；后端同学写好一个JSON接口逻辑，直接在AndroidWebServer的serve()方法里return一个new NanoHTTPD.Response(...)，前端立刻就能拿到真实数据。没有代理、没有证书、没有中间层，只有最原始的HTTP请求与响应，在局域网这个可信小圈子里，它反而成了最可靠、最透明的协作桥梁。

2. 整体设计与思路拆解：为什么选NanoHTTPD而不是其他方案

在决定把这个功能塞进Android App之前，我其实踩过不少坑，也对比过至少五种不同的技术路径。最终锁定NanoHTTPD，不是因为它名气最大，而是它在“嵌入式”这个特定维度上，给出了最平衡、最务实的答案。下面我把当时的选型思考过程摊开来讲，帮你避开那些我花了一周才绕出来的弯路。

2.1 对比方案：为什么不是Jetty、Tomcat或Spring Boot？

第一反应，很多人会想到“既然要跑Web服务，那就用成熟的Java Web容器呗”。Jetty和Tomcat确实是行业标杆，功能完整，生态丰富。但把它们塞进Android里，就像给自行车装涡轮增压——理论上可行，实际代价巨大。Jetty 9.x的最小依赖集（jetty-server + jetty-http + jetty-util）打包下来超过3MB，光是jetty-server-9.4.43.v20210629.jar一个文件就1.2MB。更致命的是兼容性：Jetty大量使用了Java NIO的高级特性（如AsynchronousSocketChannel），而Android的ART虚拟机对这些API的支持并不一致，尤其在Android 5.0以下版本，你会遇到一堆NoSuchMethodError。Spring Boot就更不用提了，它本质上是个应用框架，依赖Spring Core、Spring Web等一整套生态，光是spring-web-5.3.30.jar就2.1MB，加上自动配置、条件化加载等机制，启动一个最简服务需要加载上百个类，冷启动时间轻松突破3秒，这对一个需要快速响应的调试工具来说是不可接受的。

提示：有开发者尝试过用Spring Boot for Android的魔改版，结果发现它为了兼容Android，阉割掉了大部分核心功能，最后剩下的只是一个比NanoHTTPD还重、还难用的半成品。

2.2 为什么不是OkHttp Server或自研Socket？

OkHttp是Android上最主流的HTTP客户端库，但它本身不提供服务端能力。社区里确实有人基于OkHttp的底层Socket封装了一个简易服务端，但这类方案往往只处理GET请求，对POST Body的解析、MIME类型识别、URL编码解码等细节都极其粗糙。我试过一个开源的OkHttp-Server Demo，当它收到一个带中文参数的GET请求（如/api?name=张三）时，因为没正确处理%E5%BC%A0%E4%B8%89的URL解码，直接返回了乱码。而NanoHTTPD在NanoHTTPD.parseParameters()方法里，已经内置了完整的RFC 3986兼容解码逻辑，连+号代表空格这种边缘case都照顾到了。

至于“自己写Socket”，听起来很硬核，也很自由。我确实动手写过一个纯Socket的HTTP服务原型：监听端口、readLine()读取请求行、手动解析GET /path HTTP/1.1、再writeBytes()返回HTTP/1.1 200 OK\r\n...。但很快我就意识到，这根本不是在造轮子，而是在重复发明HTTP协议本身。一个健壮的服务端必须处理：
- 请求头大小写不敏感（Content-Type 和 content-type 要等价）
- Connection: keep-alive 的连接复用逻辑
- Content-Length 和 Transfer-Encoding: chunked 的Body读取差异
- Expect: 100-continue 的预检响应
- 安全相关的Header过滤（如X-Forwarded-For防伪造）

NanoHTTPD把这些都封装好了，而且它的源码非常干净，核心逻辑就集中在NanoHTTPD.java一个文件里（2.2.0版本约2500行），你想改哪里，直接打开就能看到，不像Jetty那样层层抽象，找一个handle()方法要跳转七八次。

2.3 NanoHTTPD 2.2.0：老版本的“稳”字诀

你可能会疑惑：为什么项目固定用2.2.0这个看起来有点老的版本？最新版不是已经到3.x了吗？答案很简单：稳定性压倒一切。NanoHTTPD 3.x引入了Java 8的Lambda语法和新的异步API，这在Android上意味着你需要开启desugaring（代码脱糖），而desugaring在某些旧版Gradle插件（如3.6.4）下会产生Duplicate class冲突。更重要的是，3.x的线程模型做了重构，从简单的ExecutorService切换到了更复杂的ScheduledThreadPoolExecutor，在低内存的Android设备上，偶尔会出现线程泄漏导致服务假死的问题——这个Bug我在一个Android 6.0的测试机上复现了三次，每次都是连续启停服务20次后触发。

而2.2.0版本，它诞生于Android 4.x仍是主流的时代，对Dalvik/ART虚拟机的兼容性经过了海量真实设备的验证。它的线程模型极其朴素：一个ServerRunnable对象，内部持有一个ServerSocket，accept()阻塞等待连接，每来一个新连接，就交给一个Worker线程去处理。这个Worker线程执行完serve()回调后，立刻关闭Socket并退出。没有复杂的线程池管理，没有定时任务调度，逻辑清晰到可以画出一张A4纸就能装下的流程图。这种“笨办法”，恰恰是嵌入式场景下最可靠的方案。就像老式机械手表，零件少、故障点少、经得起摔打。

2.4 架构设计：为什么是“继承扩展”而非“配置驱动”

项目文档里反复提到“可直接继承扩展的AndroidWebServer类模板”，这个设计选择背后，是对Android开发范式的深刻理解。很多Web框架喜欢搞一套YAML或JSON配置文件，让你在里面写port: 8080, static_dir: ./assets/www。但在Android里，这种做法是反模式的。原因有二：

第一，资源路径是动态的。Android的assets目录在APK里是只读的，你无法在运行时往里面写文件；而getFilesDir()或getExternalFilesDir()这些可写目录，其绝对路径在不同设备、不同Android版本上可能完全不同（比如/data/data/com.example.app/files/ vs /sdcard/Android/data/com.example.app/files/）。如果你把静态文件路径硬编码在配置文件里，一旦APK签名或安装路径变化，服务就直接报FileNotFoundException。

第二，生命周期必须与Activity/Service强绑定。一个Web服务不能脱离Android组件独立存活。它必须在Application.onCreate()里初始化，在Activity.onPause()或Service.onDestroy()里优雅停止。如果用配置驱动，你很难把start()和stop()的调用时机，精准地嵌入到Android的生命周期钩子中。而采用“继承AndroidWebServer”的方式，你可以在自己的MyDebugService extends AndroidWebServer里，直接重写onStartCommand()和onDestroy()，把服务的启停逻辑，无缝编织进Android的系统调度里。

这个设计让整个项目从“一个独立的Web服务器”变成了“App的一个可管理组件”，这才是它能真正落地、被长期维护的关键。

3. 核心细节解析与实操要点：从代码结构到关键陷阱

拿到这个资源包，你第一眼看到的可能是WebServerApp.java和app/src/main/java/下的目录结构。但真正决定这个服务能否跑起来、跑得稳、跑得安全的，其实是那些藏在build.gradle、proguard-rules.pro和AndroidWebServer基类里的细节。下面我带你一层层剥开，告诉你每个文件为什么这么写，以及那些不写在README里的“潜规则”。

3.1 Gradle构建配置：不只是加一行依赖那么简单

build.gradle（Module: app）里的这行依赖：

implementation 'org.nanohttpd:nanohttpd:2.2.0'

看起来平平无奇，但背后有两个关键点必须确认：

第一，implementation而非compile。compile是旧版Gradle的写法，早已废弃。用implementation能确保NanoHTTPD的API只对当前Module可见，不会意外泄露给其他依赖模块，避免潜在的类冲突。更重要的是，它能优化构建速度——Gradle在增量编译时，如果nanohttpd的代码没变，就不会重新编译所有引用它的类。

第二，版本号必须严格锁定为2.2.0。千万别手滑写成2.2.+或2.+。Maven的版本通配符在Android项目里是颗定时炸弹。我曾经在一个项目里用了2.+，某天CI服务器自动拉取了2.3.1，结果发现新版本把Response.IStatus这个枚举类改成了接口，导致我们所有new NanoHTTPD.Response(Status.OK, ...)的调用全部编译失败。锁定版本是保证构建可重现的铁律。

此外，build.gradle里还藏着一个容易被忽略的配置：

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_7
        targetCompatibility JavaVersion.VERSION_1_7
    }
}

这是强制指定Java 7兼容性。NanoHTTPD 2.2.0是用Java 7写的，它没有用到Java 8的Stream或Optional。如果你的项目默认是Java 8，而没加这个配置，某些老旧的Android设备（尤其是ARMv7架构的Android 4.x）在加载NanoHTTPD的class文件时，会抛出java.lang.UnsupportedClassVersionError。这个错误不会在编译时报，而是在运行时、在特定设备上才出现，排查起来极其痛苦。所以，宁可多写两行，也要把兼容性钉死。

3.2 AndroidWebServer基类：那个被重写的`serve()`方法

src/main/java/com/example/webserver/AndroidWebServer.java是整个项目的“心脏”。它不是一个可以直接new的对象，而是一个抽象基类，你必须继承它，并实现最关键的serve()方法。让我们看看它的骨架：

public abstract class AndroidWebServer extends NanoHTTPD {
    public AndroidWebServer(int port) {
        super(port);
    }

    @Override
    public Response serve(IHTTPSession session) {
        // 这里是你的业务逻辑入口！
        String uri = session.getUri();
        Method method = session.getMethod();

        if (method == Method.GET && uri.equals("/")) {
            return serveIndex(session);
        } else if (method == Method.GET && uri.startsWith("/api/")) {
            return serveApi(session);
        } else if (method == Method.POST && uri.equals("/upload")) {
            return serveUpload(session);
        } else {
            return newFixedLengthResponse(Response.Status.NOT_FOUND, MIME_PLAINTEXT, "Not Found");
        }
    }

    protected abstract Response serveIndex(IHTTPSession session);
    protected abstract Response serveApi(IHTTPSession session);
    protected abstract Response serveUpload(IHTTPSession session);
}

这个设计的精妙之处在于：它把HTTP协议的解析（session.getUri(), session.getMethod()）和业务逻辑的分发（if/else if路由）完全分离。你作为使用者，只需要关心“我的App要提供哪些接口”，而不用操心Content-Length怎么读、multipart/form-data怎么解析这些底层脏活——NanoHTTPD已经帮你做好了。

但这里有个致命陷阱：serve()方法是在NanoHTTPD的工作线程里被调用的，它不是Android主线程（UI Thread）。这意味着，如果你在serveIndex()里直接调用Toast.makeText(...).show()，或者更新TextView.setText()，会立刻抛出CalledFromWrongThreadException。正确的做法是，把需要更新UI的操作，通过Handler或runOnUiThread()切回主线程。例如：

// 错误！会在工作线程里操作UI
private Response serveIndex(IHTTPSession session) {
    Toast.makeText(this, "有人访问了首页！", Toast.LENGTH_SHORT).show(); // CRASH!
    return newFixedLengthResponse("Hello from Android!");
}

// 正确！安全地切回主线程
private Response serveIndex(IHTTPSession session) {
    final Context context = this; // 假设this是Activity或Application上下文
    new Handler(Looper.getMainLooper()).post(() -> {
        Toast.makeText(context, "有人访问了首页！", Toast.LENGTH_SHORT).show();
    });
    return newFixedLengthResponse("Hello from Android!");
}

这个细节，90%的初学者都会踩坑，也是为什么项目强调“适合有Android开发基础的开发者”的原因——你得懂Android的线程模型。

3.3 ProGuard混淆规则：为什么`proguard-rules.pro`里要保留`NanoHTTPD`？

当你准备发布APK时，ProGuard会自动混淆你的代码，把AndroidWebServer变成a，把serve()变成a()。这本身没问题，但NanoHTTPD的内部反射机制，要求它的核心类名和方法名必须保持原样。比如，NanoHTTPD在解析multipart/form-data时，会通过Class.forName("org.nanohttpd.protocols.http.tempfiles.DefaultTempFileManager")来加载临时文件管理器。如果DefaultTempFileManager被混淆成b，这个forName()就会失败，导致所有文件上传请求都无法处理。

因此，proguard-rules.pro里必须有这一行：

-keep class org.nanohttpd.** { *; }

它告诉ProGuard：“org.nanohttpd包下的所有类、所有方法、所有字段，一个字节都别动”。这个规则看似粗暴，但却是最稳妥的做法。NanoHTTPD本身代码量很小（整个jar才200KB），保留它对最终APK体积的影响微乎其微（通常<50KB），却能避免一堆难以定位的运行时异常。

注意：有些开发者会尝试更精细的规则，比如只保留NanoHTTPD类和Response类。但实践证明，NanoHTTPD的内部依赖链很隐蔽，比如DefaultTempFileManager又依赖File和RandomAccessFile，稍有不慎就会漏掉某个关键类。所以，“宁可多留，不可少留”，是处理第三方库混淆的黄金法则。

3.4 网络绑定与端口选择：`0.0.0.0`不是万能钥匙

在实例化AndroidWebServer时，你可能会看到这样的代码：

AndroidWebServer server = new MyWebServer(8080);
server.start();

这里，8080是端口号，但还有一个更关键的参数——绑定地址（bind address）。NanoHTTPD的构造函数支持三个参数：

public NanoHTTPD(String hostname, int port)
public NanoHTTPD(InetAddress bindAddr, int port)

如果你只传一个int port，它默认绑定到localhost（即127.0.0.1），这意味着服务只能被本机访问，局域网内的其他设备根本连不上！这就是为什么很多新手照着README跑起来后，电脑浏览器打不开手机IP的原因。

正确的做法是显式指定绑定地址：

try {
    // 绑定到所有可用网络接口（Wi-Fi、热点、USB网卡）
    InetAddress bindAddr = InetAddress.getByName("0.0.0.0");
    AndroidWebServer server = new MyWebServer(bindAddr, 8080);
    server.start();
} catch (UnknownHostException e) {
    Log.e("WebServer", "Failed to bind to 0.0.0.0", e);
}

0.0.0.0是一个特殊的IP地址，意思是“监听本机所有网卡”。但这里有个隐藏风险：如果你的手机同时连着Wi-Fi和开启了个人热点，0.0.0.0会让服务同时暴露在两个网络里。对于调试场景，这通常是OK的；但对于生产环境的工具App，你可能只想让它在Wi-Fi内网可用，这时就应该获取当前Wi-Fi的IP，然后绑定到那个具体的地址。

如何获取Wi-Fi IP？可以用这段经典代码：

WifiManager wifiManager = (WifiManager) getSystemService(Context.WIFI_SERVICE);
int ipAddress = wifiManager.getConnectionInfo().getIpAddress();
if (ipAddress != 0) {
    String ipString = String.format("%d.%d.%d.%d",
        (ipAddress & 0xff),
        (ipAddress >> 8 & 0xff),
        (ipAddress >> 16 & 0xff),
        (ipAddress >> 24 & 0xff));
    InetAddress bindAddr = InetAddress.getByName(ipString);
    server = new MyWebServer(bindAddr, 8080);
}

这段代码的健壮性在于：它只在Wi-Fi已连接且获取到IP时才执行绑定，否则回退到0.0.0.0。这比硬编码一个IP要可靠得多。

4. 实操过程与核心环节实现：从零开始搭建你的第一个服务

现在，我们把前面所有的理论知识，变成一个可执行、可验证的完整流程。我会以一个最典型的场景为例：为你的App添加一个“本地H5页面预览”功能。目标是：用户点击App里的一个按钮，启动Web服务，然后在手机浏览器或电脑浏览器里输入http://[手机IP]:8080，就能看到你放在assets/www/目录下的index.html。

4.1 第一步：准备静态资源与目录结构

首先，在你的Android项目里，创建标准的Web资源目录。Android Studio默认的assets目录是完美的存放位置，因为它会被打包进APK，且路径固定。在app/src/main/assets/下，新建一个www文件夹，然后放入你的H5页面：

app/src/main/assets/www/
├── index.html
├── style.css
└── script.js

index.html的内容可以很简单：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Android本地预览</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>欢迎来到Android Web服务器！</h1>
    <p>当前时间：<span id="time"></span></p>
    <script src="script.js"></script>
</body>
</html>

style.css和script.js可以是任意内容，关键是验证静态文件服务是否生效。注意：assets目录里的文件，在APK里是以只读方式存在的，NanoHTTPD无法向其中写入文件，所以这个服务只支持“读取”静态资源，不支持“上传”覆盖。

4.2 第二步：编写继承类`MyWebServer`

在app/src/main/java/com/yourpackage/下，新建一个Java类MyWebServer.java，继承AndroidWebServer：

package com.yourpackage;

import android.content.Context;
import android.util.Log;
import org.nanohttpd.protocols.http.NanoHTTPD;
import org.nanohttpd.protocols.http.response.Response;
import org.nanohttpd.protocols.http.response.Status;
import org.nanohttpd.util.MimeType;

import java.io.IOException;
import java.io.InputStream;
import java.net.InetAddress;

public class MyWebServer extends AndroidWebServer {

    private final Context mContext;

    public MyWebServer(Context context, int port) {
        super(port);
        this.mContext = context.getApplicationContext(); // 使用Application Context，避免内存泄漏
    }

    @Override
    protected Response serveIndex(NanoHTTPD.IHTTPSession session) {
        // 尝试从assets/www/下读取index.html
        try {
            InputStream is = mContext.getAssets().open("www/index.html");
            byte[] data = new byte[is.available()];
            is.read(data);
            is.close();
            return newFixedLengthResponse(Status.OK, MimeType.HTML.toString(), data);
        } catch (IOException e) {
            Log.e("MyWebServer", "Failed to load index.html", e);
            return newFixedLengthResponse(Status.INTERNAL_ERROR, MimeType.PLAINTEXT.toString(), "Internal Error");
        }
    }

    @Override
    protected Response serveApi(NanoHTTPD.IHTTPSession session) {
        // 这里可以返回JSON数据，供H5页面AJAX调用
        String json = "{\"status\":\"success\",\"message\":\"Hello from Android!\",\"timestamp\":" + System.currentTimeMillis() + "}";
        return newFixedLengthResponse(Status.OK, MimeType.JSON.toString(), json);
    }

    @Override
    protected Response serveUpload(NanoHTTPD.IHTTPSession session) {
        // 暂时不实现上传逻辑
        return newFixedLengthResponse(Status.NOT_IMPLEMENTED, MimeType.PLAINTEXT.toString(), "Upload not supported");
    }
}

这个类做了几件关键事：
- 构造函数接收Context，并用getApplicationContext()存储，避免持有Activity引用导致内存泄漏。
- serveIndex()方法从assets目录读取www/index.html，并以text/html MIME类型返回。注意is.available()在这里是安全的，因为assets里的文件大小是确定的。
- serveApi()提供了一个简单的JSON接口，演示如何返回结构化数据。

4.3 第三步：在Activity中启动与停止服务

在你的主Activity（比如MainActivity.java）里，添加启动和停止逻辑：

public class MainActivity extends AppCompatActivity {

    private MyWebServer mWebServer;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        Button btnStart = findViewById(R.id.btn_start_server);
        btnStart.setOnClickListener(v -> startWebServer());

        Button btnStop = findViewById(R.id.btn_stop_server);
        btnStop.setOnClickListener(v -> stopWebServer());
    }

    private void startWebServer() {
        try {
            // 获取Wi-Fi IP，如果获取不到则用0.0.0.0
            InetAddress bindAddr = getWifiInetAddress();
            if (bindAddr == null) {
                bindAddr = InetAddress.getByName("0.0.0.0");
            }
            mWebServer = new MyWebServer(this, 8080);
            mWebServer.setInetAddress(bindAddr); // 关键！设置绑定地址
            mWebServer.start();
            Toast.makeText(this, "Web服务器已启动！访问 http://" + getLocalIpAddress() + ":8080", Toast.LENGTH_LONG).show();
        } catch (Exception e) {
            Log.e("MainActivity", "Failed to start web server", e);
            Toast.makeText(this, "启动失败：" + e.getMessage(), Toast.LENGTH_LONG).show();
        }
    }

    private void stopWebServer() {
        if (mWebServer != null) {
            mWebServer.stop();
            mWebServer = null;
            Toast.makeText(this, "Web服务器已停止", Toast.LENGTH_SHORT).show();
        }
    }

    // 辅助方法：获取本机IP地址（用于Toast提示）
    private String getLocalIpAddress() {
        try {
            for (Enumeration<NetworkInterface> en = NetworkInterface.getNetworkInterfaces(); en.hasMoreElements();) {
                NetworkInterface intf = en.nextElement();
                for (Enumeration<InetAddress> enumIpAddr = intf.getInetAddresses(); enumIpAddr.hasMoreElements();) {
                    InetAddress inetAddress = enumIpAddr.nextElement();
                    if (!inetAddress.isLoopbackAddress() && inetAddress instanceof Inet4Address) {
                        return inetAddress.getHostAddress();
                    }
                }
            }
        } catch (SocketException ex) {
            Log.e("MainActivity", "getLocalIpAddress() exception", ex);
        }
        return "127.0.0.1";
    }

    // 辅助方法：获取Wi-Fi IP地址（用于绑定）
    private InetAddress getWifiInetAddress() {
        WifiManager wifiManager = (WifiManager) getApplicationContext().getSystemService(Context.WIFI_SERVICE);
        if (wifiManager != null && wifiManager.isWifiEnabled()) {
            int ipAddress = wifiManager.getConnectionInfo().getIpAddress();
            if (ipAddress != 0) {
                try {
                    return InetAddress.getByAddress(new byte[]{
                        (byte) (ipAddress & 0xff),
                        (byte) (ipAddress >> 8 & 0xff),
                        (byte) (ipAddress >> 16 & 0xff),
                        (byte) (ipAddress >> 24 & 0xff)
                    });
                } catch (UnknownHostException e) {
                    Log.e("MainActivity", "Invalid IP address", e);
                }
            }
        }
        return null;
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        stopWebServer(); // 确保Activity销毁时服务也停止
    }
}

这段代码的关键点：
- mWebServer.setInetAddress(bindAddr)是启动前必须调用的，否则它会默认绑定到localhost。
- onDestroy()里调用stopWebServer()，确保用户退出Activity时，服务不会在后台偷偷运行，浪费电量和网络资源。
- getLocalIpAddress()方法遍历所有网卡，找到第一个非回环的IPv4地址，用于在Toast里显示给用户看，方便他复制粘贴到浏览器。

4.4 第四步：配置AndroidManifest.xml与权限

在app/src/main/AndroidManifest.xml里，确保你已经声明了网络权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

ACCESS_WIFI_STATE是可选的，只用于getWifiInetAddress()方法获取Wi-Fi状态。如果你不关心精确绑定Wi-Fi IP，只用0.0.0.0，那么这个权限也可以去掉。

4.5 第五步：运行与验证

编译并安装APK到你的Android手机上。打开App，点击“启动Web服务器”按钮。你应该会看到一个Toast提示，类似：

Web服务器已启动！访问 http://192.168.1.105:8080

现在，拿出你的笔记本电脑，确保它和手机连在同一个Wi-Fi网络下。打开浏览器，输入http://192.168.1.105:8080（把IP换成你手机的实际IP）。如果一切顺利，你将看到index.html渲染出的页面！

为了进一步验证，你可以在index.html里加一段JavaScript，调用我们刚才写的API：

<script>
fetch('http://192.168.1.105:8080/api')
    .then(response => response.json())
    .then(data => {
        document.getElementById('time').textContent = new Date(data.timestamp).toLocaleString();
    });
</script>

刷新页面，你会发现页面上的时间被动态更新了——这证明你的H5页面不仅能展示静态内容，还能与Android原生逻辑进行双向通信。

5. 常见问题与排查技巧实录：那些文档里不会写的“血泪史”

在把这套方案推广给团队其他成员的过程中，我收集了超过30个真实发生的问题。下面我挑出其中最高频、最棘手的5个，配上我当时是如何一步步定位、分析、最终解决的全过程。这些经验，比任何官方文档都管用。

5.1 问题1：电脑浏览器打不开`http://[手机IP]:8080`，显示“连接已拒绝”

现象：手机上Toast显示服务已启动，IP地址也正确，但电脑浏览器一直报错ERR_CONNECTION_REFUSED。

排查思路：
1. 先确认手机自身是否能访问：在手机浏览器里直接输入http://127.0.0.1:8080。如果能打开，说明服务进程本身是OK的，问题出在网络可达性上。
2. 检查防火墙：Android系统本身没有传统意义上的防火墙，但某些国产ROM（如MIUI、EMUI）会自带“网络助手”或“流量监控”，默认阻止非系统App的后台网络监听。进入手机“设置 > 网络和互联网 > 流量使用情况 > 应用联网”，找到你的App，确保“Wi-Fi”开关是打开的。
3. 验证端口是否被占用：另一个App（比如某个P2P下载工具）可能已经占用了8080端口。在手机上用ADB命令检查：
bash adb shell netstat -tuln | grep :8080
如果输出为空，说明端口空闲；如果有输出，说明已被占用。此时，修改你的MyWebServer构造函数，换一个端口，比如8081或9000。

终极解决方案：在startWebServer()方法里，加入端口探测逻辑：

private int findAvailablePort(int startPort) {
    for (int port = startPort; port < 65535; port++) {
        try {
            new ServerSocket(port).close();
            return port;
        } catch (IOException e) {
            // 端口被占用，继续下一个
        }
    }
    return startPort; // 找不到就用默认的
}
// 启动时调用
int actualPort = findAvailablePort(8080);
mWebServer = new MyWebServer(this, actualPort);

5.2 问题2：`assets/www/index.html`里的CSS和JS文件404

现象：index.html能正常显示，但页面样式错乱，控制台报错GET http://192.168.1.105:8080/style.css 404 (Not Found)。

原因分析：index.html里写的<link rel="stylesheet" href="style.css">，浏览器会向服务器发起一个对/style.css的GET请求。但我们的MyWebServer.serve()方法里，只处理了/和/api/开头的URI，对/style.css直接返回了404。

解决方案：扩展serve()方法，增加对静态资源的泛匹配：

@Override
public Response serve(IHTTPSession session) {
    String uri = session.getUri();
    Method method = session.getMethod();

    // 新增：处理所有以 /www/ 开头的静态资源请求
    if (method == Method.GET && uri.startsWith("/www/")) {
        String assetPath = "www/" + uri.substring(5); // 去掉 "/www/" 前缀
        return serveAsset(assetPath);
    }

    // ... 其他原有的 if/else 分支 ...
}

private Response serveAsset(String assetPath) {
    try {
        InputStream is = mContext.getAssets().open(assetPath);
        String mimeType = getMimeTypeForAsset(assetPath);
        byte[] data = new byte[is.available()];
        is.read(data);
        is.close();
        return newFixedLengthResponse(Status.OK, mimeType, data);
    } catch (Exception e) {
        Log.e("MyWebServer", "Failed to load asset: " + assetPath, e);
        return newFixedLengthResponse(Status.NOT_FOUND, MimeType.PLAINTEXT.toString(), "Asset Not Found");
    }
}

private String getMimeTypeForAsset(String path) {
    if (path.endsWith(".css")) return MimeType.CSS.toString();
    if (path.endsWith(".js")) return MimeType.JAVASCRIPT.toString();
    if (path.endsWith(".png")) return MimeType.PNG.toString();
    if (path.endsWith(".jpg") || path.endsWith(".jpeg")) return MimeType.JPEG.toString();
    return MimeType.PLAINTEXT.toString();
}

这样，当浏览器请求/www/style.css时，服务会自动从assets/www/style.css读取并返回，无需为每个文件单独写一个if分支。

5.3 问题3：上传大文件时服务崩溃或超时

现象：用户通过<input type="file">上传一个5MB的图片，服务端serveUpload()还没执行完，客户端就收到ERR_CONNECTION_RESET。

根本原因：NanoHTTPD默认的tempFileManager会把上传的文件先写入一个临时目录，而Android的/data/data/your.app/cache/目录空间有限，且NanoHTTPD 2.2.0的临时文件清理逻辑不够健壮，大文件上传中途失败会导致临时文件残留，最终填满缓存区。

解决步骤：
1. 自定义临时文件管理器：创建一个CustomTempFileManager，把临时文件写入getExternalCacheDir()（SD卡缓存，空间更大）：
```java
public class CustomTempFileManager implements TempFileManager {
private final File mCacheDir;

   public CustomTempFileManager(Context context) {
       this.mCacheDir = context.getExternalCacheDir();
       if (!mCacheDir.exists()) mCacheDir.mkdirs();
   }

   @Override
   public TempFile createTempFile() throws Exception {
       return new CustomTempFile(mCacheDir);
   }

   @Override
   public void clear() {
       // 清理逻辑
   }

}
2. **在`MyWebServer`构造函数里注入它**：java
public MyWebServer(Context context, int port) {
super(port);
this.mContext = context.getApplicationContext();
// 设置自定义临时文件管理器
setTempFileManagerFactory(() -> new CustomTempFileManager(mContext));
}
```

5.4 问题4：服务启动后，手机Wi-Fi图标消失或断连

现象：启动Web服务几秒钟后，手机顶部状态栏的Wi-Fi图标不见了，或者App里检测到Wi-Fi已断开。

真相：这不是服务的问题，而是Android系统的“省电策略”在作祟。某些厂商（特别是华为、荣耀）的EMUI系统，会把长时间监听端口的App识别为“后台高耗电”，并主动切断其网络连接以保电。

应对策略：
- 引导用户关闭电池优化：在启动服务前，弹出一个Dialog，指导用户进入“设置 > 电池 > 电池优化 > 你的App > 不允许优化”。
- 使用前台Service：如果服务需要长时间运行，不要只在Activity里启动，而是创建一个ForegroundService，并在onStartCommand()里启动Web服务，并调用startForeground()显示一个持续的通知。这样系统就知道“这个服务很重要，别杀它”。

5.5 问题5：ProGuard混淆后，`serve()`方法里的`session.getParameters()`返回空Map

现象：Debug版本一切正常，Release版本打包后，所有GET参数都丢失了，session.getParameters()永远是空的。

根源：NanoHTTPD在解析URL参数时，会调用java.net.URLDecoder.decode()，而这个方法的反射调用链中，涉及java.lang.String的intern()方法。某些ProGuard配置（尤其是-optimizations !code/simplification/arithmetic,!field/*,!class/merging/*）会干扰字符串常量池的处理，导致解码失败。

一劳永逸的修复：在proguard-rules.pro里，追加一条针对URLDecoder的保留规则：

-keep class java.net.URLDecoder { *; }
-keep class java.net.URLEncoder { *; }

这条规则确保了URL编解码的核心类不被混淆或优化，从此参数解析再也不会失灵。

6. 进阶玩法与安全边界：让它不止于“能用”，更要“好用、安全”

当你已经熟练掌握了基础启动、静态托管和简单API之后，这个迷你Web服务器的潜力才刚刚释放。下面分享几个我在实际项目中沉淀下来的、真正提升生产力的进阶技巧，以及一条必须划清的安全红线。

6.1 技巧1：用`assets`目录模拟“热更新”开发流

在H5页面开发中，最痛苦的莫过于“改一行CSS → 重新编译APK → 重新安装 → 重启服务 → 刷新浏览器”。这个循环一次就要2分钟。我们可以利用Android assets目录的特性，实现近乎实时的“热更新”。

原理很简单：assets目录在APK里是只读的，但我们可以通过adb push命令，在不重新安装APK的情况下，把新文件推送到手机的/data/data/your.app/files/目录，然后修改serveAsset()方法，优先从这个可写目录读取文件，找不到时再fallback到assets。

具体步骤：
1. 在MyWebServer里，新增一个mOverrideDir字段，指向getFilesDir()。
2. 修改serveAsset()：
java private Response serveAsset(String assetPath) { // 1. 先尝试从可写目录读取（用于热更新） File overrideFile = new File(mOverrideDir, assetPath); if (overrideFile.exists()) { try { byte[] data = Files.readAllBytes(overrideFile.toPath()); String mimeType = getMimeTypeForAsset(assetPath); return newFixedLengthResponse(Status.OK, mimeType, data); } catch (IOException e) { Log.w("MyWebServer", "Failed to read override file", e); } } // 2. fallback到assets try { InputStream is = mContext.getAssets().open(assetPath); // ... 同之前的逻辑 } catch (Exception e) { // ... } }
3. 开发时，用命令行快速推送：
bash # 把本地的style.css推送到手机 adb push ./src/main/assets/www/style.css /data/data/com.yourpackage/files/www/style.css # 刷新浏览器，立即生效！

这个技巧，把H5开发的迭代周期从“分钟级”压缩到了“秒级”，是我团队内部的标准开发流程。

6.2 技巧2：为不同环境配置不同的服务行为

一个App可能有debug、beta、release多个构建变体（Build Variant）。我们可以通过Gradle的buildConfigField，在编译时注入不同的配置，让服务在不同环境下表现不同。

在build.gradle里：

android {
    buildTypes {
        debug {
            buildConfigField "boolean", "ENABLE_WEB_SERVER", "true"
            buildConfigField "int", "WEB_SERVER_PORT", "8080"
        }
        release {
            buildConfigField "boolean", "ENABLE_WEB_SERVER", "false"
            buildConfigField "int", "WEB_SERVER_PORT", "80"
        }
    }
}

然后在MyWebServer的构造函数里：

public MyWebServer(Context context, int port) {
    super(BuildConfig.ENABLE_WEB_SERVER ? port : 0); // 如果禁用，传0会抛异常，但我们可以捕获
    // ...
}

这样，release版本的APK里，ENABLE_WEB_SERVER是false，服务根本不会被初始化，彻底杜绝了生产环境意外暴露的风险。

6.3 安全红线：永远不要在生产环境中暴露未授权的Web服务

这是最重要的一条，也是我见过最多人踩的坑。这个迷你Web服务器，因其“开箱即用”的便利性，很容易被开发者随手集成进一个面向公众的App里。但请务必记住：一个监听在0.0.0.0上的HTTP服务，就是一个未经认证、未经审计的远程攻击面。

想象一下：你的App里有一个/api/get_logs接口，它会把手机上所有的App日志（包括可能包含密码的Logcat）原样返回。如果这个接口没有做任何访问控制，任何一个在同一Wi-Fi下的黑客，只要知道你的手机IP，就能用curl http://192.168.1.105:8080/api/get_logs把日志全部拖走。

因此，我给自己立下铁律：
- 所有生产环境的Web服务，必须有访问控制。最简单的方案，是在serve()方法开头，检查请求头里的Authorization字段，或者校验一个固定的Token参数。
- 永远不要监听0.0.0.0在生产环境。生产环境的服务，应该只绑定到127.0.0.1（仅限本机），或者通过getWifiInetAddress()绑定到具体的Wi-Fi IP，并且在服务启动后，主动扫描局域网内是否有未知设备在尝试连接（通过记录IHTTPSession.getRemoteIpAddress()并做白名单校验）。
- 敏感接口必须加密传输。虽然NanoHTTPD 2.2.0不原生支持HTTPS，但你可以用SSLSocket包装ServerSocket，或者更简单——只在调试阶段用HTTP，正式上线时，把所有敏感逻辑移到真正的后端服务器，这个Android服务只作为一个轻量的、只读的、非敏感的“状态面板”。