装 Odoo 模块时弹出「无法安装模块 xxx，因为未满足外部依赖：No module named ‘xlsxwriter’」，或者干脆报 KeyError: 'module_name'——这大概是 Odoo 二次开发里最常见的坑。依赖缺失分两种：Python 库缺失和 Odoo 模块间依赖缺失，处理方式完全不同。下面按报错类型一个个说。
先看日志，确认缺的是什么
别急着重装。先把日志翻出来：
tail -n 100 /var/log/odoo/odoo-server.log如果日志里出现 ImportError 或 No module named，缺的是 Python 库。如果是 KeyError 或「依赖模块 xxx 未找到」，缺的是另一个 Odoo 模块。这两类错在界面上的提示经常混在一起，日志才是准的。
缺 Python 库：用 Odoo 自己的环境装
最容易踩的坑是 pip 装错了环境。服务器上往往有系统 Python、venv，甚至好几个版本，你在 SSH 里随手 pip install xlsxwriter，装进的可能根本不是 Odoo 用的那个解释器。
先确认 Odoo 跑在哪个 Python 上：
ps aux | grep odoo
# 看输出里的路径，比如 /opt/odoo/venv/bin/python3然后用这个解释器对应的 pip 装：
/opt/odoo/venv/bin/pip install xlsxwriter
sudo systemctl restart odoo装完必须重启服务，Odoo 不会热加载新装的库。如果模块的 __manifest__.py 里写了 external_dependencies，把里面列的库一次装齐，省得装一个报一个。
缺 Odoo 模块：检查 depends 和 addons 路径
打开报错模块的 __manifest__.py，找 depends 字段：
'depends': ['base', 'sale', 'stock_account'],逐个核对这些模块在你的实例里是否存在。企业版模块（比如 account_accountant）在社区版里没有，第三方模块从 GitHub 拉下来时也可能漏了配套仓库。确认文件在磁盘上之后，还要检查 odoo.conf 的 addons_path 是否包含它所在的目录：
addons_path = /opt/odoo/odoo/addons,/opt/odoo/custom-addons改完配置重启服务，再到「应用」界面点右上角的「更新应用列表」（要先开开发者模式），然后重新搜模块安装。少了这一步，Odoo 的模块列表还是旧的，照样报找不到。
版本不匹配也会伪装成依赖缺失
一个 Odoo 16 的模块放到 17 里装，depends 里的模块名可能已经改名或合并了，报错看起来也是「依赖未找到」。检查模块 manifest 里的 version 字段，第一段数字要和你的 Odoo 大版本一致。版本不对就去找对应分支，别硬改代码强装，后患很多。
常见问题
FAQ
装完 Python 库重启了还是报同样的错？
九成是装错了环境。用 /opt/odoo/venv/bin/python3 -c "import xlsxwriter" 直接验证，能 import 说明装对了，报错就是路径不对。
更新应用列表后还是搜不到模块？
确认模块目录里有 __init__.py 和 __manifest__.py 两个文件，缺一个都不会被识别。另外检查目录权限，odoo 用户要能读。
生产环境能直接装依赖吗？
建议先在测试库验证。pip 装新库一般无风险，但模块安装会改数据库结构，出问题回滚很麻烦，装之前先备份数据库。
你装 Odoo 模块时遇到过什么奇怪的报错？欢迎在 fenij.com 评论区贴出日志一起分析。
