前几天帮朋友折腾一块树莓派4B朋友手边既没有HDMI显示器也没有USB键盘任务却很明确让这块板子插电就能自动连上WiFi然后我在自己电脑上SSH进去装环境。最后卡在一个非常小的细节上——Windows记事本把wpa_supplicant.conf存成了带BOM的编码树莓派死活不认。改成无BOM的纯文本后一次就连上了。这件事让我觉得值得把完整的无头配置流程好好写一篇。树莓派无头配置headless setup指的是不接显示器、不接键鼠、不插网线只靠一张SD卡和一根电源线把树莓派初始化成一台可以远程SSH登录的Linux小主机。做毕设、跑YOLO、搭家庭服务网关、做无人值守采集设备几乎都绕不开这一步。这篇文章按实际操作的顺序把烧录镜像、SD卡预埋WiFi配置、启用SSH、发现IP、连入命令行的完整链路讲清楚同时把容易踩的坑一次性列出来。全文以新手能复现为前提老手可以直接跳到最后两节看排查思路。1. 无头配置的底层逻辑树莓派凭什么“盲开机”就能联网先解释为什么SD卡能“预埋”配置。树莓派不像普通电脑有BIOS可以进设置界面它所有的启动参数都在SD卡上。树莓派上电后板载GPU先从SD卡的boot分区读取固件加载内核、挂载根文件系统然后启动systemd。无头场景下我们要做的就是在系统启动之前把“连哪个WiFi”“是否开启SSH”“创建什么用户”这三个问题用文件的方式提前告诉系统系统首次启动时读到这些文件就会执行相应操作。这就像给一个不认识路的快递员在信封背面画好路线图他还没拆开信封就已经知道往哪走。1.1 SD卡里的两个分区与“只要改boot就够了”烧录完官方镜像的SD卡会被分成两个分区boot分区FAT32约几百MB存放固件、内核、设备树以及我们可以手动放进去的预置配置文件。FAT32兼容性很好Windows、macOS、Linux插上读卡器就能读写。root分区ext4占据剩余空间系统真正的根文件系统程序、用户数据都在这里。Windows默认不认ext4macOS也不认所以无头操作要尽量避免动这个分区。这带出一个好消息无头配置需要的三个文件——wpa_supplicant.conf、ssh、userconf.txt——全部放在boot分区根目录即可完全不需要任何ext4读写工具。很多新手被“Linux文件系统”吓到其实完全没必要。烧录完镜像后SD卡在电脑上会显示为一个可移动磁盘你只需要在它的根目录新建文件或复制文件。1.2 谁来读取这些文件首次启动流程与网络服务把文件放进boot分区之后树莓派第一次上电启动时系统里的初始化流程会去检查boot分区里是否存在这些标记文件并据此完成初始化。找到wpa_supplicant.conf就把它移动到系统配置目录下并用它连接WiFi找到ssh标记文件就生成SSH服务所需的host key并启动sshd找到userconf.txt就根据里面的用户名和密码哈希创建初始账户。这个过程在经典版本的Raspberry Pi OS上非常稳定。从Bookworm版本开始官方把默认网络管理从dhcpcd换成了NetworkManager底层逻辑有变化手动放wpa_supplicant.conf的方式仍然会被首次启动流程读取但前提是你必须是一次全新烧录、从未开机配置过。如果已经开过机、进入过桌面或初始化向导再插回电脑上放这个文件就不会生效了。所以我的建议是用最新官方镜像做无头优先用Raspberry Pi Imager的高级选项来预设一步到位手动改卡的流程更适合Lite版老镜像或者想彻底理解原理的人。这也是本文接下来两条路都会讲的原因。2. 烧录镜像时的预埋技巧Imager高级选项与手动改卡两条路的取舍2.1 用Raspberry Pi Imager一步完成WiFi、SSH和用户预设官方烧录工具Raspberry Pi Imager支持在烧录前打开高级选项直接把WiFi和SSH配置一并写进SD卡这是目前最推荐的新手路线。具体流程从官网下载并安装Raspberry Pi Imager。打开后选择设备型号和操作系统。做无头建议选Raspberry Pi OS Lite无桌面版资源占用低更适合跑服务。选择SD卡然后点击齿轮图标打开高级选项Windows/Linux下快捷键是CtrlShiftXmacOS下是CommandShiftX。在高级选项里完成几项关键配置设置主机名默认raspberrypi建议改成方便识别的名字比如nas-pi。启用SSH选择“使用密码认证”也可以提前粘贴公钥做密钥认证。设置用户名和密码2022年4月后的官方镜像不再预置pi用户这一步必须做。配置无线局域网填写WiFi SSID、密码国家选择CN。保存设置后开始烧录等进度条跑完。Imager本质上做的事情和我们手动改卡一样——它会在写入完成后在boot分区生成对应的配置文件。区别在于它能帮你处理用户名、密码哈希、权限这些最容易出错的地方。对于只想快速跑起来、尤其是第一次接触树莓派的人这条路线几分钟就能点亮。2.2 手动改卡依然是必学技能批量部署与脚本化场景那手动改卡还有没有必要学我的看法是很有必要。原因有二。第一Imager是图形界面工具适合一台一台处理。如果你要部署五台、十台树莓派或者要写自动化脚本在服务器上批量烧卡图形工具就派不上用场了。手动方式只需要知道三个文件名和它们的格式写个shell脚本就能批量生成。第二理解手动改卡能帮你排障。Imager写进去的配置出了问题你要会检查它生成了什么、为什么没生效。如果你连配置文件长什么样都不知道出了问题就只能反复重刷。手动改卡要记住核心口诀boot分区根目录放wpa_supplicant.conf管WiFi放ssh管SSH开关放userconf.txt管初始用户。下面三节我就把这几个文件的细节全部讲透。3. wpa_supplicant.conf逐字段拆解写错一个字符网都连不上3.1 文件放置、文件名与换行符文件名必须是wpa_supplicant.conf注意后半部分是.conf不是.txt。Windows资源管理器默认隐藏已知文件类型的扩展名新建文本文档重命名时容易多出.txt这是新手最常翻车的地方。建议在资源管理器“查看”里勾选“文件扩展名”再重命名。文件内容的基本模板如下ctrl_interfaceDIR/var/run/wpa_supplicant GROUPnetdev update_config1 countryCN network{ ssid你的WiFi名字 psk你的WiFi密码 key_mgmtWPA-PSK }有几个细节必须强调换行符必须是LFUnix风格不能用Windows记事本默认的CRLF。如果文件用Windows记事本编辑树莓派读取时会在行尾多出一个\r可能导致配置解析失败。推荐用VSCode、Notepad编辑并在右下角把文档格式切换成LF或者先在Linux/macOS上创建好再复制进SD卡。编码建议UTF-8无BOM。BOM会在文件开头多出几个不可见字节某些解析器会把它当正常内容导致第一行配置读不出来。countryCN这一行别省略。国家码影响WiFi可用信道和5GHz频段官方推荐写你所在国家或地区也能解决一部分信道选择导致的WiFi扫描不到的问题。3.2 network块的关键参数与多个WiFi的优先级network块是配置的核心每一对花括号描述一个要连接的无线网络。常用参数就五个ssidWiFi名称字符串用双引号包住。pskWiFi密码同样用双引号。key_mgmt加密方式。家用路由器一般写WPA-PSK兼容WPA2/WPA3开放网络写NONE。priority优先级数字越大越优先连接默认是0。scan_ssidWiFi隐藏了SSID时需要设为1告诉网卡主动扫描指定SSID而不是被动等待。一个支持多个网络的完整示例network{ ssidHomeWiFi pskhome-pass priority10 } network{ ssidLabWiFi psklab-pass priority5 } network{ ssidGuest-Free key_mgmtNONE priority1 }这样配置之后树莓派在信号范围内会优先连HomeWiFi连不上再尝试LabWiFi最后才连开放网络。如果WiFi密码里包含引号、反斜杠这类特殊字符直接写在psk里容易出错。更稳妥的做法是用wpa_passphrase工具生成network块在Linux终端执行wpa_passphrase HomeWiFi pss\word它会直接输出包含散列psk字段的完整network块配置里不保存明文密码也不怕特殊字符只需要把输出复制进配置文件。3.3 校园网与企业级WiFi的连接如果你要把树莓派接进大学校园网或者公司里使用802.1X认证的WiFi上面的WPA-PSK配置就不够了。这种情况下需要指定认证协议典型配置如下network{ ssideduroam key_mgmtWPA-EAP eapPEAP identity你的学号/账号 password你的密码 phase2authMSCHAPV2 }不同单位的认证细节可能略有差异但骨架就是这个。顺带说一句很多校园网的有线网络也有认证那个不是WiFi配置能解决的需要额外处理不在本文范围。如果你只是做毕设临时用更快的验证办法是给树莓派开一个手机热点注意把热点频段设成2.4GHz配置简单排障也直观。4. ssh空文件与用户账户初始化无键盘状态下如何“登记”管理员4.1 boot分区里的ssh标记文件是怎么触发sshd的SSH服务在树莓派默认镜像里是关闭的官方给出的开启方式不只有raspi-config在无头场景下还有一个更早的技巧在boot分区根目录新建一个名为ssh的文件无扩展名内容可以为空。系统首次启动时检测到它就会生成SSH host key并启动sshd。处理完成后这个文件会被删除你插回电脑再检查时可能已经不在了这是正常现象不代表没生效。这里有两个容易踩的坑文件名不能带.txt后缀。Windows里用“新建文本文档”改名成ssh时需要在资源管理器里先把扩展名显示出来确认最终文件名是ssh而不是ssh.txt。修改这个文件之前树莓派必须是正常关机状态。直接在树莓派运行时拔SD卡再插回电脑大概率损坏文件系统。最好先执行sudo shutdown -h now等电源灯熄灭后再拔卡。4.2 新镜像的userconf.txt没有显示器也能创建用户从2022年4月发布的Raspberry Pi OS开始官方不再预置pi/raspberry这个默认账户第一次启动会要求创建用户。有显示器时很简单跟着向导填就行完全没有显示器时就得靠userconf.txt这个文件。具体做法在boot分区根目录新建userconf.txt里面只写一行格式是用户名:密码哈希用户名一般用pi就行密码哈希不能是明文必须用哈希算法加密后的结果。生成哈希有两种常见办法。在Linux或macOS终端里执行echo 你的密码 | openssl passwd -6 -stdin把输出的那一长串复制到userconf.txt的冒号后面。Windows没有直接可用的openssl命令除非装Git Bash或WSL这种情况建议直接用Imager的高级选项来设置用户省事还不会错。userconf.txt的完整示例pi:$6$randomSalt$HASHHASH...openssl生成的整串首次启动流程读了这个文件后会创建用户并设置密码然后把它从boot分区清理掉。如果你设置的用户名不是piSSH登录时记得用你自己设置的那个用户名。这个文件是无头配置里最容易被忽略的一环。很多人用最新官方镜像烧录后只放了wpa_supplicant.conf和ssh结果SSH端口能通但提示用户不存在就是因为没有初始账户。用Imager的人不存在这个问题因为高级选项里已经把用户信息写进去了。5. 开机后找IP、连SSH从完全未知到拿到命令行的完整过程5.1 四种靠谱的IP发现方式配置写入完成、SD卡插回树莓派、插电开机后接下来面临的问题是树莓派到底拿到什么IP了没有显示器这个信息不会自动出现需要主动去找。我按推荐程度排列方式操作适用场景路由器后台DHCP列表登录路由器管理页在“已连接设备”里找主机名raspberrypi最推荐能看到设备名最直观mDNS.local域名ping raspberrypi.local或ssh piraspberrypi.local局域网里同名设备少时可用Windows需要开启网络发现或装Bonjour局域网扫描nmap -sn 192.168.1.0/24或手机装Fing、Advanced IP Scanner路由器后台不显示设备名时可用arp -a先ping 192.168.1.255再arp -a兜底方案只显示IP和MAC我个人最常用的组合是先看路由器后台的主机名如果信息太少就装个nmap扫一下网段nmap -sn 192.168.1.0/24输出里能看到树莓派的IP和MAC地址。用nmap之前先确认电脑所在网段不知道的话用ipconfigWindows或ip addrLinux/macOS查。5.2 三种系统的SSH连接命令与首次登录拿到IP后就可以SSH登录了。Windows 10/11自带OpenSSH客户端直接在PowerShell或CMD里执行ssh pi192.168.1.23 # 或者用主机名 ssh piraspberrypi.localmacOS和Linux直接在终端执行同样的命令。第一次连接会出现类似“The authenticity of host ... cant be established”的提示问你是否确认连接输入yes回车即可。这是SSH在确认服务器指纹正常现象。如果提示“找不到ssh命令”说明Windows的OpenSSH客户端没装去“设置 → 应用 → 可选功能 → 添加可选功能”里找到OpenSSH客户端装上或者用Git Bash代替。登录成功后你就进入树莓派的命令行了。接下来有几件事建议马上做修改密码执行passwd输入当前密码和新密码。确认WiFi连接状态执行iwconfig或nmcli device status看wlan0有没有关联成功。查看IP和网关执行ip addr、ip route确认网络正常。如果你装了VSCode强烈推荐装Remote-SSH插件在远程资源管理器里填上pi192.168.1.23加载后就能像在本地一样打开树莓派上的代码、跑终端命令。写树莓派上的Python脚本、调试YOLO推理都会比纯命令行舒服非常多。5.3 密钥登录与Windows SSH权限翻车现场密码登录跑通之后如果想更方便可以配置SSH密钥登录。本机生成密钥ssh-keygen -t ed25519然后把公钥推到树莓派上。Linux/macOS有现成的ssh-copy-idssh-copy-id pi192.168.1.23Windows没有这个命令可以手动执行type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh pi192.168.1.23 mkdir -p ~/.ssh cat ~/.ssh/authorized_keys这一步做完以后SSH登录就不再需要密码了。然后有个Windows特有坑如果你编辑了~/.ssh/config文件OpenSSH客户端会检查它的访问权限权限过宽会直接报“Bad owner or permissions on C:\Users\xxx.ssh\config”然后退出。修复办法是移除文件继承的Everyone权限只保留当前用户完全控制或者用命令icacls %USERPROFILE%\.ssh\config /inheritance:r /grant:r %USERNAME%:F这个报错很常见每次都是Windows上手动建了config文件后出现属于典型的“文件能用但权限不对”。6. 连不上时的排查链路按顺序检查这四层无头配置成功率再高也总会遇到一次连不上的情况。没有显示器排障不能靠眼睛看必须靠线索链路。我的经验是按下述四层顺序逐层排查每层都有明确的判断方法和处理动作。6.1 第一层树莓派到底上线了没有开机的第一反馈是板载指示灯。红灯亮代表供电正常绿灯闪烁代表SD卡有读写活动。如果红灯直接灭掉或者板子反复重启大概率是供电不足。树莓派4B建议使用官方5V 3A电源树莓派5对供电要求更高建议用5V 5A电源加好一点的USB-C线。劣质电源和数据线在WiFi高负载时会掉压表现就是刚连接成功又断或者干脆起不来。供电确认无误后打开路由器管理后台看“已连接设备”列表里有没有新设备。树莓派默认主机名是raspberrypi如果列表里什么都没多出来说明WiFi没连上问题大概率出在wpa_supplicant.conf上回第3节检查。有些场景下没有路由器后台比如在公司、学校网络最快的验证办法是用手机开热点热点里连接设备少一眼就能看出来。注意把热点频段设成2.4GHz因为部分老型号只支持2.4GHz5GHz热点扫不到。6.2 第二层WiFi关联和IP分配的状态设备已经出现在路由器列表里但电脑SSH连不上这时要看关联状态是否健康。如果设备列表里能看到树莓派但IP一直在变检查路由器DHCP设置如果树莓派在线但电脑ping不通它的IP最常见的原因是路由器开了AP隔离也叫“访客网络隔离”或“无线隔离”。这种模式下无线客户端之间禁止互通树莓派能上网但局域网内其他设备访问不到它。解决方式是在路由器设置里关闭AP隔离或者把树莓派和电脑都接到同一个非隔离SSID下。另外要注意树莓派拿到IP不代表SSH一定能连上它可能在线但IP和MAC对不上。可以在路由器里把树莓派的MAC地址绑定一个固定IP无头设备后面远程维护会省很多事。6.3 第三层22端口是否在监听树莓派在线、IP也能ping通接下来检查SSH端口。在电脑上执行Windows PowerShellTest-NetConnection 192.168.1.23 -Port 22Linux/macOSnc -zv 192.168.1.23 22如果显示22端口不通原因基本是SSH服务没起来。这时把SD卡插回电脑检查boot分区里的ssh文件是不是被Windows加上了.txt后缀或者文件名是不是不小心写成了sshd。如果用的是Bookworm系统且不是全新烧录系统不会重新读取标记文件这种情况只能重刷镜像或者在树莓派接入有线网络后手动开启SSH。端口通但提示“Permission denied (publickey,password)”这是认证层面的问题用户名写错了、密码不对或者Imager高级选项里勾选了“仅允许公钥认证”但公钥没配好。这种报错不会告诉你具体是用户名还是密码问题逐一排除即可。6.4 第四层高频翻车现场汇总最后放一张我按遇到频率整理的排查表现象可能原因处理方式WiFi完全连不上country没填或编码无效补上countryCN重新烧录配置WiFi连上但SSH超时手机热点开了5GHz老设备不支持热点切到2.4GHzssh文件放进去仍无法连接文件变成了ssh.txt显示扩展名去掉.txt用户密码正确但登录失败新镜像没有默认pi用户userconf.txt没放用Imager预设用户或补userconf.txt重刷能连接但频繁断开供电不足或WiFi省电模式换更高功率电源关闭wlan0的powersave每次开机IP都变DHCP租约不稳定路由器里做MAC绑定固定IPWindows下SSH报config权限错误~/.ssh/config权限过宽icacls命令收紧权限这里再说一个排障原则一次只改一个变量。改完配置文件后正常关机、拔卡、插回电脑改、再插回树莓派开机、等一到两分钟看效果。不要同时改WiFi、SSH和用户否则出问题你根本不知道是哪个环节挂的。从我个人的实操经验来看无头配置最磨人的不是技术细节而是你永远看不到启动过程的“盲人摸象感”。所以第一次调试的时候我强烈建议把路由器后台开在电脑屏幕上插电后盯着设备列表看看到raspberrypi出现的那一刻后面所有排障就都有了锚点。等这套流程跑顺了你会发现树莓派变成了一台真正能远程无人值守的小服务器后续无论是挂脚本、跑模型还是连各种外设都不过是SSH进去之后的事情了。