简介资源包提供Android WIFI基础操作的教学示例面向刚接触系统服务调用的移动开发学习者基于WifiManager实现Wi-Fi的开启、关闭与状态监听。内容涵盖完整Java源码、APK安装包及项目配置文件共33个文件包含java源文件、class编译文件、xml资源配置、png图片资源及工程相关文件整体压缩包仅143KB结构精简适合快速阅读与导入工程。包内已生成可直接安装的APK便于对照运行查看效果同时附有状态判断逻辑与权限配置说明可帮助理解ACCESS_WIFI_STATE等权限声明方式。已有224人学习下载适合作为Android系统服务入门的小型练手资源。 做Android开发的人十有八九都经历过这种场景数据线接触不良adb装包装到一半直接断连或者手头同时有好几台测试机USB口根本不够用再或者公司配的笔记本USB口只有一个插了调试线就没法插U盘。我前两年天天背着电脑和一堆线到处跑后来花了一个下午把WIFI调试彻底搞顺之后工作效率提升非常明显。这篇文章就从实际开发的角度把Android WIFI操作里最常用的部分整理出来包括无线调试怎么配、WifiManager核心API怎么用、权限和版本差异怎么适配还有我踩过的坑。这是这个系列的第一篇适合刚接触Android开发、想把设备调试和WIFI功能玩明白的朋友也适合写了好几年业务代码但一直没系统过WIFI模块的同学。1. 先搞清楚需求Android WIFI操作到底解决什么问题1.1 开发调试场景无线调试是刚需先说我个人最常碰到的场景。日常开发中真机调试基本绕不开尤其是涉及定位、蓝牙、NFC这类硬件的功能模拟器根本没法验证。传统的USB调试方式虽然稳定但有几个明显痛点一是数据线质量参差不齐很多第三方线拿来只能充电不能传输数据排查起来很浪费时间二是频繁插拔会让手机充电口松动我有一台测试机的Type-C口就是因为长期插拔出现了接触不良三是多设备调试时需要反复拔线换设备一天下来心思全耗在插拔线上。无线调试ADB over WiFi正好解决这些问题。手机和电脑连同一个局域网通过adb命令把调试通道切到TCP/IP上就能像USB调试一样安装、看日志、抓取截图。只要网络稳定体验和USB调试几乎没有差别。这个方案在Android 11之前需要用USB线做一次“引导”Android 11开始系统提供了独立的无线调试开关连引导线都可以省掉这部分我在第3节会详细讲。很多朋友听说无线调试的第一反应是“会不会很慢”实际上在同一局域网内adb无线安装一个几十MB的测试包也就几秒钟完全在可接受范围内。1.2 业务功能场景应用内的WIFI能力除了开发调试很多App本身就有WIFI相关的业务需求。常见的有这样几种一是展示当前连接的WIFI信息比如SSID、信号强度、IP地址这类功能在企业办公App里经常出现用来做网络状态诊断二是扫描附近的WIFI列表用于网络配置或信号检测类工具三是主动连接某个WIFI比如智能硬件配网、IoT设备的初始配置流程。像随身WiFi这类硬件设备的管理工具以及智能家居的配网App核心流程基本都绕不开WIFI扫描和连接这两个步骤。这里要说明一点很多人以为Android对WIFI的控制权限非常大实际上从Android 10API 29开始Google一直在收紧WIFI相关的权限和API。比如获取当前连接的SSID需要精确定位权限连接WIFI的旧API被废弃MAC地址被随机化。这些限制不是bug而是系统设计上的隐私和安全策略顺着系统设计来写代码才是正路。有些应用想绕过系统限制结果要么在应用商店上架被打回要么在部分机型上直接崩溃得不偿失。这个系列后续我会专门写一篇关于权限变化的深度分析。2. 基础准备环境、设备和权限2.1 开发环境选型不管你是用Android Studio还是纯命令行做WIFI调试和WIFI开发都离不开两个基础工具adb和Android SDK。Windows系统需要到SDK的platform-tools目录里操作adbmacOS和Linux把platform-tools加入环境变量路径就行。Android Studio自带Android SDK我目前用的版本是Hedgehog2023.1.1 Patch 2这个版本对AGP 8.x的支持已经非常成熟SDK Manager里可以同时管理多个版本的platform-tools和build-tools非常方便。如果你的项目还在用老版本Android Studio建议至少升级到支持AGP 8的版本WIFI相关功能在较新的SDK工具链下编译会更顺畅。对于Android SDK的版本选择我建议手机端Android版本和SDK版本尽量匹配。比如测试机是Android 14就用API 34的SDK来编译Android 11对应API 30。实际工作中很多人不太在意这个编译版本低一点也能跑但遇到WIFI这类权限变化大的功能还是用目标版本对应的API来做可以减少很多兼容性问题。另外不要忘了在gradle里显式配置targetSdkVersion这个值决定了系统用哪一套运行时权限和API限制策略很多人只习惯改compileSdkVersion导致targetSdkVersion停留在一个很低的版本行为上虽然能掩盖兼容性问题但应用商店上架审核会卡住。2.2 手机端需要打开的开关无线调试前手机端有几个开关必须要确认。首先是开发者选项里的“USB调试”不管用哪种无线调试方式都离不开它其次是“无线调试”选项Android 11它藏在开发者选项的二级菜单里需要单独打开。还有一个容易被忽略的细节是“仅充电时启用USB调试”这个选项如果开着插上USB线后要在通知栏里点一下授权否则adb命令不会生效很多人反复试都连不上最后发现是这个开关的问题。这里有个经验不同品牌的手机对开发者选项的藏法不太一样有的藏在“关于手机”里连点7次版本号有的直接在“系统设置”里就能找到。我实际项目中遇到过一些定制ROM厂商会在系统层面对无线调试做额外限制比如某些旧版本的系统需要先连接数据线才能开启无线调试。遇到这种情况不要怀疑是自己的代码写错了先确认系统版本和厂商文档。另外建议把手机屏幕超时时间调长一点或者直接用adb命令改系统设置把屏保和休眠策略先关掉不然调试过程中屏幕频繁熄灭WIFI的连接稳定性会受影响。3. WIFI调试实操从USB到无线的完整切换3.1 传统方案ADB over WiFiAndroid 11之前最经典的无线调试方式是先用USB连接一次然后执行两条命令把adb服务切换到TCP/IP模式。完整流程是这样先用USB线连上手机和电脑在终端里执行adb devices确认设备已经被识别接着执行adb tcpip 5555把adb守护进程从USB传输模式切换成TCP/IP监听模式端口号5555是adb的默认调试端口。命令执行成功后终端会提示restarting in TCP mode这时候就可以拔掉USB线了。接下来要去查看手机当前在局域网内的IP地址可以到设置里的“WLAN”详情页查看也可以直接执行adb shell ip addr show wlan0从输出里找inet后面的地址。拿到IP后在电脑上执行adb connect 192.168.x.x:5555看到connected字样后再执行adb devices设备状态会从unauthorized变成device说明调试通道已经走WIFI了。之后装包、看日志、截图全和USB调试一样关键是不用再受数据线牵制。关于adb tcpip这个命令的原理可以简单理解成adb本来就有USB和TCP/IP两条传输通道默认情况下USB优先。执行adb tcpip后adb server会把后续的调试请求转发到网络通道上。所以只要手机不重启5555端口会一直监听你可以在同一网络下任何一台电脑上连接这台设备。我经常把测试机扔在工位旁边的充电座上用笔记本无线连上去操作省了不少事。这里有个小坑如果家里或者公司网络开了AP隔离设备之间互相ping不通adb connect就会一直超时这时候需要连到同一个路由器或关闭AP隔离。3.2 Android 11 的无线调试配对Android 11开始系统提供了独立的无线调试功能不需要再用USB线引导一次。操作流程是这样先把手机开发者选项里的“无线调试”打开进入子页面会看到当前设备的IP地址和端口同时有一个“使用配对码配对设备”的选项。电脑上执行adb pair 192.168.x.x:配对端口输入手机屏幕上的6位配对码回车之后设备会显示配对成功。然后再执行adb connect 192.168.x.x:连接端口注意这里的连接端口和配对端口是两个不同的端口配对端口一般是以4开头的随机端口连接端口是以3开头的随机端口。每次重启或重新打开无线调试这两个端口都可能会变需要在手机上重新看一眼。这套流程比传统方式方便很多但也有一个限制无线调试开关一旦关闭再重新打开已配对的设备可能会失效需要重新配对。如果你用的是Android Studio它的Device Explorer里其实内置了无线调试的图形化入口手机开启无线调试后在IDE里点一下就能自动配对连接不想记命令的话直接用IDE入口会容易很多。不过命令行方式还是要掌握的很多排查场景下IDE的图形化工具不一定比命令行快。3.3 每次开机后如何快速重连无线调试配好之后最影响体验的问题是手机重启。手机一重启无线调试开关默认是关闭的端口也会重置你没办法用纯无线方式重新打开它这个限制是系统层面做的安全设计不是代码能绕过去的。实测下来我比较推荐的做法是给测试机准备一条短的数据线平时就放在工位上。手机重启后先USB连一下执行adb tcpip 5555然后拔线再adb connect整个过程大概十几秒比每次重新去设置里折腾快得多。另外调试过程中如果发现无线连接又慢又不稳定先别急着换线优先检查这几个地方手机和电脑是否接入了同一个路由器连接的频段是2.4G还是5G2.4G在信号干扰大的环境里很容易掉线手机厂商自带的“WIFI智能省电”或“WLAN优化”开关是否开着有些系统默认会深度休眠时挂起WIFI数据。把这些确认一遍基本能解决八成的不稳定问题。我用了大半年无线调试最大的体会是环境配置到位之后它的稳定性其实远超预期。4. WifiManager API 常用操作与权限适配4.1 权限声明与运行时申请如果你想在应用里读取或操作WIFI状态第一步是搞定权限。在AndroidManifest.xml中至少需要声明三个权限ACCESS_WIFI_STATE用于读取WIFI状态CHANGE_WIFI_STATE用于修改WIFI状态ACCESS_FINE_LOCATION用于定位。前两个相对好理解第三个定位权限是很多人容易漏掉的。Android从6.0开始WIFI扫描和获取WIFI连接信息就需要定位权限了因为WIFI扫描结果中包含的BSSID信息可以用来推测设备的大致位置系统把WIFI信息当作定位数据来处理。运行时申请权限的代码网上很多这里提醒几个容易出错的点。一是targetSdkVersion如果大于等于23必须在代码里动态申请ACCESS_FINE_LOCATION只写在Manifest里不够二是如果用户拒绝了定位权限WIFI扫描接口不会崩溃而是返回空列表或者空值很多人以为是自己代码写错了其实是被系统静默拦截了三是Android 9开始WIFI扫描默认会返回随机化的BSSID同一个WIFI在不同设备上看到的BSSID可能不一样这是正常现象不要拿BSSID做设备绑定逻辑。我见过一个同事把BSSID当作设备唯一标识存到数据库里结果同一台路由器在不同手机上显示成了不同设备查了好久才发现是这个问题。4.2 获取当前连接WIFI的信息获取当前连接的WIFI信息是开发中使用频率最高的操作核心代码并不长。通过getSystemService拿到WifiManager然后调用getConnectionInfo()就能得到WifiInfo对象里面包含SSID、信号强度RSSI、IP地址等字段。这里有一个非常重要的细节Android 10API 29开始getConnectionInfo().getSSID()只有在你已经获取了定位权限并且应用在前台运行时才会返回真实的SSID否则会返回null或者常量值unknown ssid。不少人在Android 10以上的设备上测试这个功能时发现SSID拿不到其实就是这个原因。判断当前是否连接到WIFI我习惯用ConnectivityManager获取当前活动网络然后判断它的类型是不是TYPE_WIFI。Android 10之后getActiveNetworkInfo()被标记废弃官方推荐用NetworkCallback监听网络状态变化代码会复杂一些但属于系统推荐方向。如果只是做一个简单的状态展示旧的API仍然能工作项目压力大时不用急着全量迁移但要清楚废弃API在未来的某个版本里可能被移除技术债迟早要还。4.3 扫描附近的WIFI列表扫描WIFI列表通常配合BroadcastReceiver使用。先注册一个接收器监听扫描结果然后手动触发WifiManager.startScan()扫描完成后系统会发一个SCAN_RESULTS_AVAILABLE_ACTION广播在接收器里调用getScanResults()取出结果。ScanResult里有用的字段包括SSID、BSSID和levellevel就是信号强度的RSSI值单位是dBm一般是负数。比如-50表示信号很好-90表示很差如果你要展示信号格数需要用WifiManager.calculateSignalLevel()把RSSI转换成1到5的等级。这段逻辑有几个坑需要注意。一是startScan()是异步操作不要指望调用完马上就能拿到结果二是Android 9之后官方建议两次扫描间隔不要小于扫描周期频繁调用会被系统限频实际表现就是广播迟迟不来三是Android 13开始扫描附近WIFI需要申请NEARBY_WIFI_DEVICES权限这个权限属于“附近的设备”类别申请时机和用户提示跟定位权限不一样适配的时候要看清楚。我自己的做法是在扫描前先检查版本Android 13以上走新权限13以下走定位权限两边都覆盖才能保证在不同机型上行为一致。4.4 连接指定WIFIAndroid 10的新方式应用主动连接WIFI在Android 9之前可以用WifiManager.addNetwork()加enableNetwork()来完成但从API 29开始这些方法基本废弃了官方推荐用WifiNetworkSpecifier配合ConnectivityManager来请求网络连接。核心逻辑是创建一个NetworkRequest指定目标WIFI的SSID和密码然后通过ConnectivityManager发起请求用户会在系统弹窗里确认连接这个交互转变非常关键。连接WIFI不再像以前一样在后台静默完成而是把决策权交还给用户做智能硬件配网类应用的朋友要特别注意旧方案在Android 9及以下仍然可用但新机上的体验已经完全不同了。我在实际用WifiNetworkSpecifier时遇到的典型场景是配网工具用户选择某一个WIFI输入密码系统弹窗确认应用会收到onAvailable回调表示网络已经可用。这个流程里建议在onUnavailable回调里给用户明确的失败提示因为系统可能在10秒内找不到匹配网络回调触发时用户在界面上完全无感知很容易误以为卡死了。另外用完之后一定要在合适的时机调用unregisterNetworkCallback释放请求否则系统会持续保留这个网络请求导致用户设备一直保持在该WIFI下。5. 常见问题与排查技巧实录5.1 无线调试连不上的原因无线调试连不上是我被问得最多的问题我把常见原因整理成一个速查表方便大家收藏现象可能原因解决办法adb devices看不到设备USB调试未开启或未授权检查开发者选项插线后确认手机上的调试授权弹窗adb connect一直超时手机和电脑不在同一局域网确认连的是同一个路由器关闭AP隔离提示unable to connect端口写错或端口已变化重新查看手机无线调试页面的端口重新connect连接成功后频繁掉线WIFI信号弱或系统休眠策略关闭WIFI省电策略保持屏幕常亮换5G频段提示offlineadb版本过旧更新platform-tools重启adb服务排查这类问题我一般按固定顺序来先adb kill-server再adb start-server重启adb服务然后确认手机和电脑在同一网段再检查端口有没有变化最后才考虑是不是系统版本问题。百分之八十的无线调试问题都能靠这个顺序解决不要一上来就怀疑是板子或线的问题。5.2 扫描结果为空或拿不到SSIDWIFI扫描结果为空最常见的原因是定位权限没有被授予。前面提过光申请权限还不够很多国产ROM上还需要在系统设置里给应用打开“定位服务”开关甚至有些机型需要额外开启“WLAN扫描”的辅助定位选项。这属于厂商定制层面不同品牌差异较大测试的时候要把主流机型都过一遍。拿不到SSID的问题除了定位权限还有可能是targetSdkVersion的问题。如果你的targetSdkVersion已经升到29以上但代码还保留着Android 9及以下的逻辑就会出现行为不一致。遇到这种情况最稳妥的方式是用NetworkCallback里提供的WifiInfo回调来获取SSID而不是直接调WifiManager.getConnectionInfo()。这个回调从Android 11开始在onAvailable回调里就能拿到带SSID的WifiInfo体验比旧方案好很多。如果要在Android 10的设备上兼容也可以先判断系统版本再决定走哪条路径。核心思路是不要让业务代码感知太多底层差异把获取SSID的逻辑封装到一个方法里里面做好版本分支这样上层调用方始终拿到一个统一的字符串。5.3 Android版本差异导致的兼容性问题做WIFI开发最头疼的就是版本碎片化。我维护的一个工具类库里WIFI相关的代码光兼容分支就写了三套Android 9以下走旧的WifiManager方案Android 10和11走WifiNetworkSpecifier加定位权限方案Android 13以上又要处理NEARBY_WIFI_DEVICES权限。每一层都想清楚之后代码虽然变多了但每个分支都逻辑清晰不会互相干扰。这里建议尽量不要在业务代码里到处写版本判断最好把WIFI相关能力封装成一个独立的工具类或者模块对外暴露统一的接口内部根据Build.VERSION.SDK_INT做分发。这样后续系统升级只需要改模块内部逻辑业务层完全无感。我一开始是直接在Activity里写的后来适配到第三个版本就后悔了重构花了不少时间。另外测试的时候一定要准备一台Android 9或者以下的旧设备。不是所有用户都会第一时间升级系统旧设备上跑一遍能暴露很多新设备上看不到的问题。我自己就遇到过一台Android 8的老平板WIFI扫描后的广播接收器会收到两次回调如果不做去重处理列表会重复刷新这是个非常典型的版本差异bug。还有一次是Android 9的设备上连接WIFI成功后系统弹窗没有自动消失需要用户手动点掉跟新机上的行为完全不同。这些细节不实测根本发现不了。这个系列我准备按“基础操作”和“进阶适配”两条线继续往下写。基础部分会把今天讲到的无线调试、WifiManager核心API、权限适配再延伸一下补一些代码封装和UI展示的细节进阶部分会重点讲Android 10之后WIFI模块的架构变化、热点模式下设备间通信以及和NFC、蓝牙联动实现近场配网的完整方案。最后再分享一个小技巧。如果你像我一样经常需要在多台设备之间切换建议写个简单的脚本把常用设备的IP地址存下来一键连接。比如在macOS的~/.zshrc里定义几个alias像cwifi1、cwifi2这样的命令几秒钟就能切到目标设备比每次手动敲IP和端口省事多了。WIFI调试这东西配置一次之后日常使用真的很香但前提是把环境和脚本都准备到位不然反而会因为频繁断连降低效率。本文还有配套的精品资源点击获取