树莓派使用smbclient凭据连接本地服务器失败报错

报错核心触发原因是smbclient.register_session()接口参数格式错误：该接口的服务端入参仅接受纯服务器IP/主机名，不支持smb://协议前缀。传入带前缀的URL后，库会将完整字符串smb://192.168.119.10/作为域名进行DNS解析，自然触发「Name or service not known」解析失败错误。
系统自带文件管理器可正常连接，是因为文件管理器会自动识别剥离smb协议前缀，和Python库的参数规则不通用。

• 修正接口传参格式：去掉服务端地址的smb://前缀和末尾斜杠，全局配置过认证信息后，注册会话时无需重复传入用户名密码，修正后的测试代码如下：

import smbclient
smbclient.ClientConfig(username='TEST', password='password')
# 仅传入纯IP地址作为服务端标识
smbclient.register_session('192.168.119.10')

• 连通性校验：如果修正参数后依然报错，先在树莓派终端执行端口检测命令，确认445端口连通正常：
  nc -zv 192.168.119.10 445
  如果端口检测失败，检查系统防火墙是否限制了Python进程的出站访问，同时确认运行Python脚本的用户和桌面登录用户一致，避免用户级网络配置差异导致的连接阻断。
• 依赖版本修复：32位Raspberry Pi OS软件源中预装的smbclient相关依赖版本较旧，存在IPv6解析优先级异常的已知问题，可执行命令强制升级到最新稳定版：
  pip install --upgrade smbclient smbprotocol --force-reinstall
  升级完成后重新运行修正后的代码即可。

注意：smb://前缀仅在读写具体共享文件的路径中使用，例如读取共享目录下文件的写法为smbclient.open_file('smb://192.168.119.10/你的共享文件夹名/test.txt', mode='r')，不要将带前缀的完整文件路径传入会话注册接口。

内容的提问来源于stack exchange，提问作者o.st.