古法编程

Odoo 版本升级迁移指南

解决 Odoo 开发者面临的最大痛点：当需要对自定义模块进行大版本升级（如 v14 到 v17）时，提供详细的步骤指南和变更清单，确保迁移安全且符合官方规范。

为什么需要这个技能

Odoo 每隔几个大版本就会进行架构调整，包括 Python 版本提升、API 变更、废弃方法及视图语法的重构。如果盲目迁移，极易导致模块在升级后无法运行或出现大量报错。

本技能旨在系统化地指导开发者如何处理不同版本间的断裂性变更（Breaking Changes），并提供修复代码和检查清单，帮助你在升级后顺利运行模块。

适用场景

  • 计划将自定义 Odoo 模块从 v14、v15 或 v16 升级至 v17。
  • 在运行 odoo-upgrade 命令前，需要一份具体的检查清单。
  • 遇到升级后出现的废弃方法（Deprecated Methods）警告，需要修复代码。
  • 需要对比两个特定版本之间的 API 和语法差异。

核心工作流

  1. 确定源与目标版本：明确是从哪个旧版本迁移到哪个新版本（例如 v16 到 v17）。
  2. 分析变更清单：接收关于 API 变化、字段重命名和新视图语法的详细说明。
  3. 修复与验证：根据提供的 Before/After 代码对比修复模块，并运行验证命令确保无误。

关键版本变更速查

Odoo 16 → 17

主题 v16 旧写法 v17 新写法
视图可见性 attrs="{'invisible': [...]}" invisible="condition"
聊天气块 (Chatter) <div class="oe_chatter"> <chatter/>
必填/只读 attrs="{'required': [...]}" required="condition"
Python 最低要求 3.10 3.10+
JS 模块 遗留 define(['web.core']) ES 模块 import 语法

Odoo 15 → 16

主题 v15 旧写法 v16 新写法
网站发布标志 website_published = True is_published = True
邮件别名 alias_domain 在公司模型上 移至 mail.alias.domain 模型
报告渲染 _render_qweb_pdf() 方法签名变更
邮件线程 mail_thread_id 已废弃；改用 message_ids

示例代码

示例 1：将 attrs 可见性迁移至 v17 

<!-- v16 — domain-based attrs -->
<field name="discount" attrs="{'invisible': [('product_type', '!=', 'service')]}"/>
<field name="discount" attrs="{'required': [('state', '=', 'sale')]}"/>

<!-- v17 — inline Python expressions -->
<field name="discount" invisible="product_type != 'service'"/>
<field name="discount" required="state == 'sale'"/>

示例 2：迁移 Chatter 块 

<!-- v16 -->
<div class="oe_chatter">
    <field name="message_follower_ids"/>
    <field name="activity_ids"/>
    <field name="message_ids"/>
</div>

<!-- v17 -->
<chatter/>

示例 3：迁移 website_published 标志 (v15 → v16) 

# v15
record.website_published = True

# v16+
record.is_published = True

最佳实践与注意事项

  • ✅ 建议： 在部署到生产环境前，在每次版本上运行 --update=your_module 进行升级测试。
  • ✅ 建议： 使用官方 Odoo 升级指南 获取自动化的预升级分析报告。
  • ✅ 建议： 检查 OCA 迁移说明和模块的 HISTORY.rst 以获取社区模块的迁移信息。
  • ✅ 建议： 迁移后运行 npm run validate 以尽早发现 manifest 或 frontmatter 问题。
  • ❌ 禁止： 跳过中间版本直接跳跃（如 v14→v16），必须按 v14→v15→v16→v17 顺序进行。
  • ❌ 禁止： 忘记更新 __manifest__.py 中的 version 字段（例如 17.0.1.0.0）。
  • ❌ 禁止： 假设 OCA 模块完全兼容，需检查其 GitHub 分支是否有目标版本分支。

限制说明

  • 仅覆盖 v14 至 v17，不支持 v13 或更早期（pre-manifest 时代的结构根本不同）。
  • Odoo.sh 自动化升级路径涉及额外步骤，请查阅 Odoo.sh 文档。
  • 企业版特定模块（如 account_accountant）可能有未记录的断裂性变更，需在带有企业许可的测试环境验证。
  • JavaScript OWL 组件迁移（v15 遗留→v16 OWL）内容复杂，本技能未完全覆盖。

下载和安装

下载 odoo-migration-helper 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的文档。

你可能还需要

暂无推荐