使用PyInstaller打包ipfsapi脚本时遇模块缺失与MultiAddr解析错误

问题根源 #

1. PyInstaller未自动收集依赖模块：multiaddr库的codecs子模块（如idna、ip4等）是动态导入的，PyInstaller的静态分析无法识别，导致打包后缺失，触发ModuleNotFoundError并间接引发MultiAddr解析失败。
2. 模块导入阶段触发隐式连接：ipfsapi/ipfshttpclient在导入时会默认初始化节点地址（/dns/localhost/tcp/5001/http），即使本地没运行IPFS节点，导入阶段就会尝试解析这个地址，缺失的codecs模块直接导致解析崩溃，甚至没机会执行脚本开头的打印语句。

解决步骤 #

1. 强制PyInstaller收集缺失的multiaddr子模块 #

直接在打包命令中添加--hidden-import参数，指定所有需要的codecs模块：

pyinstaller --onefile \
  --hidden-import=multiaddr.codecs.idna \
  --hidden-import=multiaddr.codecs.ip4 \
  --hidden-import=multiaddr.codecs.tcp \
  --hidden-import=multiaddr.codecs.http \
  your_script.py

或者创建PyInstaller钩子文件hook-multiaddr.py，内容如下：

hiddenimports = [
    'multiaddr.codecs.idna',
    'multiaddr.codecs.ip4',
    'multiaddr.codecs.tcp',
    'multiaddr.codecs.http'
]

打包时通过--additional-hooks-dir指定钩子所在目录：

pyinstaller --onefile --additional-hooks-dir=. your_script.py

2. 延迟IPFS客户端初始化，避免导入阶段触发连接 #

修改脚本，不要在全局作用域初始化IPFS客户端，而是将初始化逻辑放在函数内部，延迟到需要使用时再执行：

# 仅导入模块，不初始化客户端
import ipfshttpclient

def upload_to_ipfs(file_path):
    # 延迟初始化，可自定义节点地址
    api = ipfshttpclient.Client('/ip4/127.0.0.1/tcp/5001/http')
    result = api.add(file_path)
    return result['Hash']

def download_from_ipfs(cid, save_path):
    api = ipfshttpclient.Client('/ip4/127.0.0.1/tcp/5001/http')
    api.get(cid, save_path)

# 脚本入口
if __name__ == '__main__':
    print("脚本启动...")
    # 在这里调用上传/下载函数

这样导入模块时不会触发地址解析，只有当实际调用函数时才会初始化客户端，即使本地没IPFS节点，也能正常启动脚本并处理后续逻辑（比如提示用户启动节点）。

3. 验证依赖版本兼容性 #

确保使用的ipfshttpclient是最新稳定版（替代旧的ipfsapi），同时更新multiaddr库：

pip install --upgrade ipfshttpclient multiaddr

新版本的库可能修复了部分动态导入的问题，减少PyInstaller打包的兼容性问题。

内容的提问来源于stack exchange，提问作者Matias Salimbene