有段时间没更新Odoo实操笔记了手头这本“odoo-091”的本子已经攒了不少东西。今天这篇是社群和私信里被问得最多的问题之一debug模式到底怎么打开很多刚接触Odoo的人会在别人的截图里看到一个“小虫子”图标或者在左侧菜单里看到“技术”这一栏但自己照着点怎么都找不到以为自己装了个假Odoo。真不是安装的问题而是Odoo对开发者功能的入口设计得太隐蔽没摸到门道时确实找不到。这篇文章把我在本地开发、客户现场维护、升级项目里实际用过的几种启用debug模式的方法一次性整理出来从最无脑的URL加参数、登录页点版本号、新版设置页的“激活开发者模式”按钮到配置文件常驻和快捷键传参都会说到。不管你是要做二次开发、接手旧项目维护还是只想临时把某个字段的标签改一下基本都能在里面找到适合你场景的那一种。1. 搞懂Odoo的debug模式它不是调试器而是编辑器1.1 debug模式下你能改什么不能改什么先说一个我见过太多人误解的点Odoo的debug模式不是说像PyCharm或VS Code那样可以打断点、单步跟踪Python代码。它更像是一个后端管理入口的“装修模式”打开之后你能看到平时被隐藏起来的技术字段、底层模型、视图XML结构还可以直接在页面上改字段布局和标签。具体来说打开debug模式后会发生三件肉眼可见的事情。第一页面右上角或表单视图顶部出现一个“小虫子”样式的调试菜单图标点开后会有“编辑视图”“编辑表单视图”“编辑列表视图”“测试”等入口。第二主菜单里会多出“技术”这个分类里面包含模型、视图、动作、菜单定义、定时任务、Email模板这些底层配置。第三表单视图里的每个字段上方会出现一个铅笔图标点击就能直接改字段的标签、占位符、颜色等显示属性。那不能改什么呢它改不了模型的核心逻辑比如某个字段到底是存储型还是计算型某个onchange方法触发了什么代码这些都在Python代码里。debug模式能让你看到底层定义但真要动逻辑还是要改代码文件和升级模块。我见过不少客户在debug模式下把某个字段从“必填”改成“非必填”保存时发现根本没变化就是这个原因——视图层能改的是展示模型层的约束在对应模型属性里不在视图里。1.2 为什么Odoo把开发者功能藏得这么深其实这个设计值得细品。Odoo是典型的“一个应用满足所有角色”的架构同一个页面上普通业务员只需要填单、审批财务要看金额、科目而开发者要的是字段名、模型关系、视图结构。如果把这些技术菜单和编辑入口全铺在默认界面上普通人打开系统就会看到一堆莫名其妙的选项误操作的概率会高很多。所以Odoo采用了一个很聪明的做法开发者痕迹只对显式声明“我要进入开发模式”的会话开放。它在路由层做了判断只有带特定URL参数或用户主动点击激活的请求后端才会在渲染时把那些技术菜单、编辑按钮放出来。换句话说不是功能不存在而是这段渲染逻辑默认对普通会话是关闭的。理解了这一层你就明白为什么每次刷新后debug状态会消失、为什么换了个书签地址进去又变成普通模式因为这些都是会话级状态跟着你的登录态和当前URL走。这也提醒了一件事在正式环境里如果你突然看到“技术”菜单出现那这个用户大概率是开了debug模式需要留意一下是不是临时调试完忘了关闭。2. 打开debug模式的五种方法按场景选一种就够2.1 最快最通用地址栏加?debug1这是我日常使用频率最高、也是零成本的一种方法任何版本、任何页面都适用。原理就是让浏览器往后端请求时带上debug参数后端识别到这个参数就会在这个会话里打开开发者渲染逻辑。具体操作看你要在哪个页面打开debug。比如你当前在销售订单列表页地址栏大概是这样的http://localhost:8069/web#actionxxxmodelsale.orderview_typelist你不需要动从#开始的这一大段只要在/web后面加上?debug1也就是改成http://localhost:8069/web?debug1#actionxxxmodelsale.orderview_typelist输入后按回车页面刷新一次右上角就会出现那个小虫子图标。如果你的地址不是/web而是/odoo开头的新版本路径也是一样的规则在/odoo后面加?debug1就对了。这里有一个特别容易踩的坑参数一定要放在#符号之前不能放在#之后。我见过好几个同事在长长的action参数串末尾随手补了个?debug1结果怎么刷新都不生效因为#后面的内容只是前端路由的一部分浏览器根本不会把它当查询参数发给后端。你要是发现加完没反应第一件事就去检查?debug1是不是被放在了#后面。还有个小技巧如果你已经登录了想快速回到普通模式把?debug1改成?debug0再回车或者干脆去掉参数刷新都会回到普通界面。不需要退出登录再重新进。2.2 不想记参数登录页点击Odoo版本号这个方法在传统版本尤其是12.0到16.0这段时间里非常流行因为它不需要你记任何参数只要用鼠标点两下。操作路径是先退出登录回到登录页面。在登录页的左下角或右下角你会看到一个灰色的版本号文字比如“Odoo 16”或“Odoo 17”。点击这个版本号会弹出一个“关于Odoo”的窗口。在这个窗口里再次点击版本号文字有的版本是点击中间的Odoo图标页面就会自动刷新并进入debug模式。这个方法我用过很多次在旧项目现场特别方便因为客户经常记不住URL参数电话里我跟他说“在登录页点一下版本号”比教他改地址栏快得多。但到了17.0之后这个入口在新版本里变了。部分新发行版把登录页的版本号点击行为改掉了点了只会弹出信息窗口再点也不会激活debug。如果你点了几次都没反应别纠结直接切到URL参数法或者用下面要说的新版设置页按钮。这种变化不同版本、不同小版本之间还有差异所以我的建议是别把某个版本的入口当成铁律记住“URL参数法永远可用”就够了其他的都是锦上添花。2.3 开发环境常驻配置文件与启动参数如果你是在本地开发环境长期调试每次都手动加?debug1确实很烦尤其是经常要重启服务、切换数据库的时候。这时候更合理的做法是在服务启动层面把开发模式直接打开让所有请求默认就带debug状态。老版本的Odoo17.0之前支持在启动命令里加--dev参数这是我早年最常用的做法./odoo-bin --addons-pathaddons --devall加上--devall之后除了debug模式它还会自动启用代码热重载、XML视图改动检测、静态资源不缓存这些对开发特别友好的特性。开发时改个Python文件服务自动刷新改完视图XML刷新页面就能看到效果不用反复重启服务实测提升效率非常明显。到了17.0这个命令行参数被移除了新版本的做法是在配置文件odoo.conf里加一个配置项dev_mode all注意新版本的写法不再叫dev而是dev_mode取值规则和旧的--dev类似all是全部开启。配置好后重启服务debug模式就会对当前这个数据库的所有会话默认打开。这种方式的适用场景很明确只推荐在本地开发、测试环境使用。如果是在客户的生产服务器上千万别为了图方便在配置里开dev_mode理由后面章节会专门讲你只要记住生产环境默认关闭这个配置就好。2.4 新版本17.0的“激活开发者模式”按钮新版本虽然把登录页点版本号的路子堵了一部分但也给了一个更直观的官方入口设置界面底部的“激活开发者模式”按钮。操作步骤很简单登录系统后进入“设置”应用下拉到页面最底部。如果你当前不是debug状态页面底部会有一个淡色的按钮区域上面写着“激活开发者模式”。点击它系统会自动刷新刷新完成后设置页的顶部菜单栏里就会出现“开发者工具”这一项页面右上角的小虫子图标也随之出现。我用过几次这个入口体验上确实比改URL更友好尤其是给那种只会用鼠标操作、不熟悉技术人员用语的新同事远程指导时说“打开设置拉到底部点那个激活开发者模式的按钮”清晰明了几乎不会有歧义。需要注意一个细节这个按钮只有在管理员账户下才默认显示。如果你用的是一个普通业务人员账号登录就算拉到设置页底部也看不到它。这时候你需要先切换成管理员身份或者用URL参数法绕过去。要关闭的话同样到设置页面底部会发现那个按钮变成了“关闭开发者模式”点击后刷新页面就恢复正常了。2.5 管理员专用快捷键关于窗口里的组合键还有两个偏门但有用的入口同时知道的人不多我在这里一并说一下。第一个是在“关于Odoo”窗口里按快捷键。先通过登录页点击版本号或登录后右上角头像菜单里的“关于Odoo”打开这个窗口然后按下CtrlShiftC组合键部分旧版本是AltCtrlShiftC系统同样会激活debug模式。这个方法的好处是全程鼠标键盘都不用离开桌面缺点是不同版本对组合键的支持有过调整在新版本上不保证每次都能触发。第二个更偏门是在Odoo命令行工具里对特定数据库做操作时可以用shell进入交互环境后直接修改配置参数但这属于比较进阶的玩法而且要小心改动会持久化到数据库的ir_config_parameter表里平时用不上了解即可。把上面几种方法放到一起对比一下你就能更清楚它们各自的定位了方法操作成本持久性适用版本推荐场景URL加?debug1最低当前会话全版本日常最推荐登录页点版本号低当前会话12.0-16.0为主现场远程指导配置文件dev_mode中长期17.0后为dev_mode旧版--dev本地开发设置页底部按钮低当前会话17.0新版本图形化操作关于窗口快捷键低当前会话视版本而定特殊场景备用我的经验是本地开发优先用配置文件日常调试用URL参数给客户远程指导用设置页按钮。剩下两个方法知道就行别指望靠它们过活。3. debug1之外的那些参数一次讲清楚3.1 debug0、debug1、debugassets到底有什么区别很多文章只说“加?debug1就能进开发者模式”但Odoo实际支持的debug参数值不止一个不同取值对应的调试能力是不同的。先看最常用的?debug1。它等价于开启完整的开发者模式所有技术菜单、编辑视图入口、测试入口都会开放。日常修改视图、查看字段定义、排查界面问题时用这个就够。然后是?debug0这其实是显式关闭debug模式的写法。正常情况下你只要把参数去掉再刷新就能退出debug但在某些情况下比如你之前开启过debug且系统记住了状态或者你是从某个带debug的链接跳转过来的用?debug0强制指定关闭会更可靠。再来说说?debugassets。这个参数的意义是让前端资源不再合并压缩而是把每个模块的JS和CSS单独加载出来。很多人可能不理解这有什么好处我举个例子你就明白了。正常模式下Odoo会把所有模块的静态资源打包成几个合并文件浏览器看到的是一个巨大的JS文件和一个巨大的CSS文件代码全部挤在一起你想排查是哪个模块的样式出了问题在合并文件里根本无从下手。而debugassets模式下每个模块的资源文件都是独立加载的浏览器开发者工具里能清楚看到每个文件对应的模块定位问题就精确多了。我在处理一些前端样式覆盖问题时就很依赖这个参数。比如客户说某个按钮颜色不对普通模式下一个CSS文件几千行根本找不到是哪行样式起了作用先切到debugassets再打开浏览器控制台直接能看到样式来自哪一个模块的哪个文件精准定位效率高很多。但注意debugassets会让页面加载速度明显变慢因为原本一次请求能加载完的资源被拆成了几十上百个小请求。调试完成之后记得切回?debug1或?debug0不然你可能会误以为项目性能出了问题。3.2 开启debug后菜单里多出来的“技术”和“测试”当你真正打开debug模式后最直观的变化是左侧主菜单多了一个“技术”大分类这个分类下藏着一大堆平时看不到的底层配置入口。经常被用到的有这些“模型”查看系统里所有数据模型的列表点进去能看到每个模型的字段定义、类型、关系属性。做字段调整或排查数据问题时这里是第一站。“视图”所有视图定义的XML源码和结构都在这里。如果忘了某个视图是在哪个模块定义的、继承关系是什么来这个菜单查最准确。“动作”对应的是各个窗口动作window actions点击某个动作能看到它绑定的模型、视图类型、应用菜单等。“定时动作”自动化任务、定期任务的配置中心主要用于排查那些“为什么定时任务没跑”的问题。“队列”异步任务队列的管理界面Odoo 17开始大量功能默认走队列这里能看到任务执行状态和报错信息。另外表单视图右上角的小虫子菜单里还有一个“测试”子菜单从技术角度说这是开发模式下快速运行单元测试的入口。点击后会跳转到测试执行页面选择应用的测试集合即可运行。但这里的测试运行效果受限于当前数据库是否配置了测试库环境我在实际项目中很少用界面跑测试更多还是用命令行方式在CI阶段统一执行。不管怎么说debug模式下多出来的这些菜单是技术人员平时最重要的“后院”。你在界面上做任何操作最后都能回到这些底层对象里找到对应记录。4. 实战演示开启debug模式后完成一次视图调整4.1 从URL到视图编辑器完整走一遍理论讲了半天落到实操上才是真功夫。我给你完整演示一次不写一行代码用debug模式把销售订单表单上“客户参考”字段的标签改成“客户合同编号”。第一步打开浏览器访问销售订单列表页。地址栏长这样http://localhost:8069/web#actionxxxmodelsale.orderview_typelist第二步在/web后面插入?debug1得到http://localhost:8069/web?debug1#actionxxxmodelsale.orderview_typelist回车后页面刷新右上角出现小虫子图标。第三步进入任意一张销售订单的表单视图。此时表单上每个字段上方都会出现一个铅笔样式的图标鼠标悬停上去能看到字段的技术名比如“客户参考”这个字段的技术名可能是client_order_ref。这个信息在普通模式下是看不到的而现在你可以直接在页面上确认字段的真实名称这对后续写Python代码或XML视图修改特别有帮助。第四步点击“客户参考”字段上方的铅笔图标。页面会弹出一个编辑字段的对话框里面有可以修改的标签、占位提示文字、样式选项等。把“客户参考”改成“客户合同编号”点保存。第五步刷新页面查看效果。正常情况下“客户参考”已经变成了“客户合同编号”。如果没变看后面的缓存问题排查。整个过程用时可能还不到一分钟。这就是debug模式最典型的应用之一不用进入后端代码仓库直接在生产界面完成用户能感知到的字段文案调整。4.2 视图编辑器的四个常用操作新手照抄即可除了改字段标签debug模式下的视图编辑器里还有几个高频操作我做二次开发时经常用到一并列出来。第一个是移动字段位置。在表单视图中每个字段的铅笔图标旁边还有一个上下方向的箭头图标。点击这个箭头可以在当前页面直接调整字段的显示顺序。我遇到过客户说“这个字段放太下面了我要把它挪到第二个位置”以前的做法是去XML视图里数位置数错了还要来回试现在直接在界面上拖所见即所得保存后立马生效。第二个是隐藏字段。如果想临时让某个字段不在界面上显示点击铅笔图标进入编辑状态找到“不可见”选项勾上保存后这个字段就隐藏了。注意这里的隐藏只是视图层的显示控制字段数据还在数据库里不会删除任何内容。第三个是添加字段。在视图编辑器里你还能看到这个模型下所有字段的列表包括那些没有在当前视图上显示的字段。可以拖一个新的字段到视图里或者通过“添加字段”按钮选择后把它摆上去。这个操作本质上是在生成一条视图继承记录对没有编程基础的人来说等于用图形化方式完成了一次简单的XML视图修改。第四个是查看视图继承链。在小虫子菜单里选择“编辑视图”后弹窗里会显示这个视图的架构信息包含它的外部ID、继承视图列表。排查“为什么我改了视图没生效”时这个功能能告诉你是不是有其他视图在你之后做了继承覆盖把你的字段又藏回去了。4.3 改坏视图以后怎么回滚说实话用debug模式改视图虽然方便但误操作的风险也真实存在。我见过不止一个人改了字段标签后忘记原值或者隐藏了一个重要字段找不到恢复入口。这里给你三条救命的回滚思路按优先级排序。第一条如果你只是在编辑字段对话框里改了标签没勾选其他奇怪选项直接再点击铅笔图标改回去就行这是最简单的回滚。第二条如果隐藏字段后不知道怎么恢复回到技术菜单的“视图”里找到对应视图记录查看它的“继承视图”列表删除你刚才操作产生的那条继承记录即可。debug模式的图形化修改本质上都会生成视图继承记录删掉它等于撤销修改。第三条如果视图嵌套比较深改完界面完全乱了最稳妥的方案是打开技术菜单里的“视图”记录复制视图的XML源码对照源码把误改的部分手工恢复。这个方法要求你能看懂XML视图结构但只要你平时接触过一点Odoo的视图语法读起来问题不大。我个人的习惯是在任何重要视图上做图形化修改之前先把原始XML源码复制一份存到本地文本文件里。这个习惯帮我避免了好几次“改完发现客户不满意、找回原值找半天”的尴尬。一段XML几百行存一分也不占地方但关键时刻能省一晚上的排查时间。5. 常见问题与生产环境避坑手册5.1 最常踩的五个坑对照检查根据我这些年在各类项目里遇到的情况把debug模式相关的高频问题整理成了一份速查表你遇到的问题九成都能在里面找到对应解法。现象可能原因解决办法加了?debug1但图标没出现参数被放在了#号后面把参数移到#号之前刷新图标出现但点击“技术”菜单为空当前账号权限不足或数据库不是管理员环境换管理员账号登录刷新页面后debug状态丢失debug是会话级状态正常现象重新加URL参数或用配置文件常驻页面加载变慢请求数量暴增可能是debugassets模式切换为debug1或debug0视图修改保存后界面没反应浏览器缓存了旧资源或视图继承被其他视图覆盖清除浏览器缓存检查继承视图这里面有两个值得展开说说的点。第一关于缓存问题。Odoo前端资源是有版本号控制缓存的当你通过debug模式改了视图服务端的渲染逻辑会更新但浏览器缓存可能还保留着旧页面。遇到这种情况最省事的做法是CtrlShiftR强制刷新或者直接开启无痕窗口访问页面。改完视图不生效时优先怀疑缓存不要一上来就怀疑自己改错了。第二关于权限问题。如果你登录的是一个标准化配置过的账号即便开了debug技术菜单可能依然不完整。因为Odoo对于技术菜单的可见性不只是看debug参数还会叠加用户组的权限判断。碰到这种情况要么切管理员账号要么给对应用户组加上允许访问技术菜单的权限。这两条路都走不通时检查一下是不是用了自定义用户组把技术菜单权限覆盖了。5.2 为什么我不建议在生产环境长期开debug这是今天最重要的一段也是我在做项目维护时每次都要跟客户强调的事。首先从性能层面说。debug模式下前端资源默认不缓存每个页面加载都要重新拼接和传输大量开发用资源页面响应速度会有明显下降。如果你的系统同时在线几十个用户开着debug会让所有人都觉得系统变慢但真正开debug的可能只有那一个人。其次从安全层面说。debug模式把技术菜单全部暴露出来意味着有权限的用户可以看到系统的模型结构、字段定义、数据库配置信息这些信息本身就有一定敏感性。如果这个用户不小心进入了定时任务或队列管理页面误操作暂停或删除了关键任务记录后续排查成本会非常高。我见过客户误操作把邮件队列清空结果当天的自动客户邮件全部没发出去追了好几天数据才恢复。再次从稳定性层面说。debug模式下的图形化视图修改本质上是往数据库里写入视图继承记录。如果修改的人不专业改完保存了一个结构不完整的视图轻则某个页面打不开重则整个应用模块的页面都白屏。生产环境白屏对业务的影响不需要我多说。所以我的建议很明确生产环境不要长期开debug最多就是某位技术人员需要在当前会话里排查问题时临时开一下用完马上用?debug0关闭或退出登录。那正式环境里确实需要改字段标签这类简单需求怎么办我的习惯做法是先在本地开发环境把改动做完生成一份迁移脚本或XML文件再通过模块升级的方式部署到生产。如果实在紧急必须直接在页面改也至少要在改之前把原始视图源码备份好改完立即退出debug模式并确保只有管理员账号可见这个入口。还有一个小细节我在很多环境里都会主动在配置层面把技术菜单的访问权限收紧即便是管理员账号非必要也不开debug。这样能最大程度避免“顺手点了一下”导致的意外修改。这里说的“收紧”不是为了限制开发者的正常使用而是防止那些记不住入口的人误触。最后再分享一个我自己的使用习惯日常在浏览器里我很少点设置按钮进debug因为那会打断操作流。我习惯直接在地址栏按CtrlL选中地址然后手补?debug1回车页面一刷新就进状态了。调试完再按一次把?debug1改成?debug0回车退出。整个流程不到十秒不用进任何菜单也不会留下长期开启的状态。这套流程跟了我好几个项目简单、可靠、也容易教给别人。你上手之后也可以试试看找到自己最顺手的那一种其他方法就当备用方案备着吧。