企业官网建设流程全解析

PyCharm 装完之后，Xodoo 项目能不能顺利跑起来、断点能不能停住、代码跳转能不能指到正确的继承链上，靠的都是一些细节设置。这篇我按自己搭环境顺序写：装 IDE、建虚拟环境、打开项目、配解释器、配运行参数、调断点，最后给一份问题速查表。新手能直接照着做，配过几次的人也建议对比检查思路。

1. Xodoo 环境配置的整体思路与选型考量

1.1 Xodoo 这类项目对编辑器有什么特殊要求

Xodoo 的代码组织方式和普通 Python Web 项目不太一样。它把框架核心、几百个官方模块、你自己写的业务模块、XML 数据文件、QWeb 前端模板、JavaScript 资源全部放在同一个源码树里。一个再普通不过的按钮点击，调用链可能从视图定义的 XML 出发，进 controller，再进 model 的 ORM 方法，一路上要跨七八个文件。你手里如果没有一个能全局搜索、能跳转定义、能在 ORM 方法里下断点的工具，读代码基本等于摸黑。

我用过纯文本编辑器看这套代码，结果是每次想确认某个字段从哪继承过来，只能靠 grep 出几十个结果再一条条肉眼比对，效率低到令人发指。换成 PyCharm 之后最直接的收益有三个：Ctrl+点击能顺着继承链跳到父类方法；Ctrl+Shift+F能在整个源码树里精确搜到某个字段定义；打断点之后能在 Variables 面板里直接把self.env.context、self.read()的结果摊开看。这三件事撑起了日常开发的大部分效率。

所以这里的环境配置目标很明确：让 IDE 认得这个源码树的包结构，让解释器认得项目依赖，让运行配置能一键把服务带起来，让调试器能停在你想停的那一行。四件事缺一件，都会在后续开发里反复折腾。

1.2 三层隔离：系统 Python、虚拟环境、项目解释器

新手最容易犯的错，是拿系统装的那份 Python 直接 pip 装依赖。装的时候挺爽，等到第二个项目需要另一个大版本的框架，或者某个依赖升级把现有的搞崩了，就开始互相打架。

我的做法是三层隔离。系统 Python 只当引导器，什么都不装；每个项目根目录外挂一个独立虚拟环境，依赖全装在里面；PyCharm 里把项目解释器指到这个虚拟环境上。这样删项目的时候，直接连虚拟环境文件夹一起删掉，系统干干净净。

数据库这一层同理。开发库、演示库、临时测试库分开建，配置文件里用-d参数切换。别在同一个库上又跑演示数据又跑你的实验脚本，改坏了想回滚都没地方回。配置文件我习惯放在项目外的conf/目录，并且写死在版本控制忽略列表里，因为里面大概率有数据库密码。

1.3 版本对齐：先确认框架分支，再决定 Python 版本

这一步必须前置，顺序反了会浪费半天。Xodoo 的不同大版本分支对 Python 版本有硬性要求，版本不对，pip install -r requirements.txt阶段就会有一堆依赖装不上，或者装上了运行时在collections、asyncio这些标准库的接口上报错。

下面这张表是我自己整理的对应关系思路，具体数字以你手上分支的官方说明为准：

我的习惯是：拿到源码后第一件事不是装依赖，而是打开setup.py和requirements.txt，看里面有没有python_requires之类的声明，再对照分支说明确认。宁可多花五分钟确认，也不要装完一堆依赖之后发现全白干。

另外数据库这边也要留意。框架靠 ORM 访问数据库，但建库、建角色这一步是它自己完成的，所以连接用的数据库账号需要有建库权限。很多人配完连接串发现启动时报权限不足，就是账号被建成了只读或者没有建库权限的普通角色。

2. PyCharm 的安装与基础环境准备

2.1 社区版还是专业版，该怎么选

这个问题我被问过很多次。结论是：如果你只做纯 Python 后端开发和断点调试，社区版完全够用；如果你重度依赖数据库面板、需要附加到已运行进程调试、或者要做远程开发，那就上专业版。

对 Xodoo 日常开发来说，真正拉开差距的是数据库面板和附加调试这两项。数据库面板能让你不切客户端就直接看某张表的数据，排查字段存错值时非常省事。附加调试的用处是：服务已经用命令行跑起来了，你想临时抓一次请求的上下文，不用重启服务就能挂上调试器。

提示：不要为了“功能全”硬上专业版然后又去折腾破解，直接把需求拆开——社区版负责写代码和断点，数据库用独立客户端看，两边配合完全够用。

2.2 安装过程中的几个关键选项

安装包一路下一步就行，但有几个勾选项值得停下来看一眼。

安装路径不要带中文、不要带空格。这一点是老生常谈但每年都有人中招。某些依赖在编译阶段对路径里的空格处理不好，报错信息还特别含糊，排查起来能耗掉一整天。我一般固定在某个纯英文短路径下，比如D:\tools\ide这种。

“添加到 PATH”这个选项建议不勾。IDE 本身不需要命令行启动，勾了反而可能和系统上其他工具的环境变量冲突。需要命令行启动的时候，用 IDE 自带的命令行启动器就够了。

“关联文件类型”按需勾选。如果你系统上已经有其他编辑器是.py的默认打开方式，勾了会把它抢过去，看你自己的习惯。我个人不勾，工程文件通过项目方式打开更符合使用习惯。

第一次启动会让你选主题、导入已有配置。选深色主题、不导入配置，从干净状态开始，避免继承一堆自己都不记得改过什么的旧设置。

2.3 首次启动后必须改的几项基础设置

装好之后先别急着打开项目，把下面几项基础设施调好，后面会省很多事。

在 Settings 里找到 Editor > Code Style > Python，把 Tab 换成空格，缩进宽度设成 4。Python 社区规范如此，混用 Tab 和空格在多人协作时会产生无意义的 diff。

Editor > File Encodings，把 Global Encoding、Project Encoding、Default encoding for properties files 全部设成 UTF-8。Xodoo 的 XML 数据文件里经常有中文，编码不统一会出现读出来是乱码、写回去变问号的情况。

Editor > General > Auto Save，设成失焦自动保存。这个纯属个人偏好，但写 XML 视图的时候频繁手动保存真的很烦。

Appearance 里把字体调大一点，行高拉到 1.2 左右。长期盯着代码看，行距挤在一起眼睛很累，这个投入回报比很高。

2.4 虚拟环境的创建与依赖安装

打开项目根目录之后，在 Settings > Project > Python Interpreter 里点添加解释器，选 Virtualenv Environment，位置放在项目外一层目录，基础解释器选你确认过的那个版本。

创建完虚拟环境，装依赖有两种方式。命令行方式更透明：打开 IDE 底部的 Terminal，它默认已经激活了当前项目的虚拟环境，直接执行：

python -m pip install --upgrade pip pip install -r requirements.txt

如果依赖下载很慢，换成团队内部或访问更顺畅的软件源，具体地址问你们运维或者看团队文档，不要随便用网上抄来的地址。

装的过程中最容易卡住的是那几个需要本地编译的依赖。某些平台上轮子（wheel）没有现成的二进制包，会走源码编译，这时候缺编译工具链就会报一大串红字。处理思路有两个：一是补上对应的编译环境；二是退一步用带二进制的发行版本替代，但要注意版本号要和requirements.txt里要求的主版本对齐，否则运行时会遇到接口不匹配的报错。

注意：依赖装完之后，一定要在 Terminal 里确认一下which python（Windows 是where python）指向的是虚拟环境里的解释器，而不是系统的。我见过不少“依赖明明装了但运行时报找不到模块”的案例，根因就是 IDE 的解释器配置和终端里实际用的不是同一个。

3. 项目导入与解释器配置的完整实操

3.1 打开项目的正确姿势

这一步错了后面全是坑。正确做法是：File > Open，选中包含框架核心目录和模块目录的那一层根目录，也就是能看到启动脚本odoo-bin的那一层。

错误的三种打开方式：直接打开odoo-bin这个单文件（IDE 会把它当成独立脚本，没有任何包结构）；打开根目录的上一层（包索引会错乱，全局搜索会扫到一堆无关文件）；打开你自己写的业务模块目录（看不到框架代码，跳转全部失效）。

打开之后，左侧项目树应该能同时看到核心代码目录、官方模块目录、以及你自定义模块的目录。如果只看到一层空壳，说明打开的位置不对，关掉重开。

3.2 把核心代码目录标记为源码根

这一步是解决“import 报红”的关键。PyCharm 判断一个import语句是否有效，靠的是它认定的源码根集合。Xodoo 的启动脚本在根目录，但核心包是以目录形式存在的，IDE 默认不会自动把它当包索引。

操作方式：在项目树里右键核心代码目录，选 Mark Directory as > Sources Root。标记完目录图标会变色，这时候代码里from xodoo import ...之类的语句红色波浪线会消失，Ctrl+点击也能跳进框架源码了。

同时把下面这几类目录标记为 Excluded：前端第三方库目录（static/lib）、依赖安装目录（node_modules）、版本控制目录（.git）、以及所有__pycache__。不排除的话，全局搜索一次会返回上百条压缩过的第三方库结果，根本没法用。排除之后搜索范围立刻清爽。

3.3 运行配置的参数逐项拆解

环境配好之后，核心就是建一个运行配置。Run > Edit Configurations > 加号 > Python。

Parameters 里的几项逐个说。

-c指定配置文件路径。不写的话框架会用默认参数，数据库连接、端口、模块路径全都不对。路径用相对路径就行，因为工作目录已经锁定了。

-d指定要操作的数据库名。开发时建议固定一个专用库，避免误操作到演示库。如果库不存在，框架在你有建库权限的时会尝试自动创建；没权限就直接报错，看到那个报错就回去查数据库账号权限。

--dev=all是开发模式开关，它打开了几件事：XML 视图和数据文件改动后不用重启服务、QWeb 模板改动即时生效、邮件不真发而是打印到日志。这个参数是日常开发效率提升最大的一项，改个视图字段刷新浏览器就能看到，不用等重启。

但有一点要特别说明：--dev=all里的 Python 代码热重载在部分平台上是不生效的。也就是说你改了.py文件，还是得手动重启服务。别以为改了没反应是 IDE 出了问题，先确认一下是不是这个原因。我自己在这上面浪费过半小时，一度以为是断点打错了地方。

3.4 配置文件模板与参数含义

配置文件我习惯长这样，可以直接抄：

[options] addons_path = addons,myaddons db_host = 127.0.0.1 db_port = 5432 db_user = xodoo_dev db_password = 换成你自己的 db_name = dev_db http_port = 8069 data_dir = ./data log_level = debug logfile = ./logs/xodoo.log

几个容易出错的地方。

addons_path是模块搜索路径，多个路径之间用英文逗号分隔，末尾不要留空格，留了会导致最后一个路径找不到。Windows 下路径分隔符建议用正斜杠，反斜杠在 ini 文件里容易被当转义符处理掉。

data_dir是存放附件、会话、生成报表的目录。不配的话会用系统默认位置，换机器的时候这些文件就找不回来了。配成项目内相对路径，整个项目可以打包带走。

log_level = debug只在排查问题时打开。日常开发用info就够了，debug 级别日志量极大，跑一天能写满好几个 G，磁盘不心疼但滚动查看很痛苦。

http_port默认 8069。同时开多个实例调试时，第二个记得改端口，不然启动直接报端口占用。

4. 断点调试、代码提示与效率配置

4.1 断点调试的正确用法

运行配置建好之后，点那个虫子图标就是调试模式启动。服务起来之后在浏览器里操作界面，触发到你打断点的方法，IDE 就会停下来。

调试 Xodoo 项目，我最常用的三个面板是 Variables、Watches、Evaluate Expression。Variables 里展开self，能看到当前记录的 id、_name、env；展开self.env.context，能看到这次请求带过来的上下文参数，很多“为什么这个字段取不到值”的问题，答案就在 context 里。Watches 里可以常驻监视某个表达式，比如self.id，每次断住都能直接看到。

Evaluate Expression 是排查利器。断住之后，你可以直接在里面敲self.read(['name','state'])看当前记录的实际数据，敲self.env['res.partner'].search_count([])看某张表的记录数。相当于在断点现场开了一个交互式终端，比在代码里插一堆 print 然后重启快得多。

条件断点也值得说。在断点的小红点上右键可以设条件，比如record.id == 42，这样只有处理到那条特定记录的时候才会停。数据量大的模块里，不加条件的断点会被几百条记录反复触发，调试根本没法进行。

4.2 多进程模式下断点为什么失效

Xodoo 支持多进程部署，配置里有个 worker 数量的参数。当这个值大于 0 时，主进程会 fork 出多个子进程处理请求，而调试器只挂在主进程上，子进程里的代码自然不会停在断点上。

解决办法很简单：开发环境把 worker 数设成 0，也就是单进程多线程模式，这样所有代码都在调试器管辖范围内，断点行为正常。

还有一个场景是附加调试：服务已经用命令行跑起来了，我不想重启，只想临时挂上调试器。这需要 IDE 支持附加到进程，附加的时候选中那个正在跑的 Python 进程即可。这个功能对临时排查线上问题时特别有用，但要注意附加时机——附加之后才会生效，附加之前已经执行过的代码看不到。

4.3 模板与 XML 文件的编辑体验优化

Xodoo 的视图定义全是 XML，QWeb 模板也是 XML 语法。IDE 对这类文件默认按普通 XML 处理，没有针对性的标签提示。

我的处理方式是：在 Settings > Editor > File Types 里确认.xml关联到 XML 文件类型，这样至少有标签成对高亮和折叠。QWeb 里的t-开头的指令没有原生提示，靠的是记住常用写法。我在 Live Templates 里存了几个高频片段，比如列表视图骨架、表单视图骨架、字段定义，敲缩写就能展开，写新视图的时候能省下大量重复劳动。

前端 JS 部分不用在 IDE 里死磕。改完之后浏览器刷新，用浏览器自己的开发者工具打断点看变量，比在 IDE 里配 JS 调试链路省事得多。

4.4 值得记住的快捷键与日常习惯

我自己的习惯是：每天开始干活前先把服务用调试模式起起来，用到的时候直接点。频繁改了 Python 代码就勤快重启，改 XML 就靠开发模式热重载。另一个习惯是把常用库的源码打开着不关，遇到不熟悉的 ORM 方法直接跳进去看实现，比翻文档快。

5. 常见问题与排查速查

5.1 现象、根因、处置的对照表

下面这张表基本覆盖了我这几年遇到的高频问题，按出现频率排序：

5.2 两个特别值得展开的坑

第一个是“报红但能跑”。这个现象的本质是 IDE 的静态分析和运行时的包解析走了两套逻辑。运行时装依赖靠的是sys.path，IDE 的报红靠的是它自己维护的源码根索引。两者不一致就会出现代码能跑但满屏红线。判断方法很简单：跑一次能不能正常启动。能启动就说明是索引问题，按 3.2 节处理；不能启动才是真的依赖没装好。

第二个是改代码没反应。这个坑我踩过不止一次，每次都是因为没区分清楚改的是哪类文件。XML 改动靠开发模式热重载，Python 改动必须重启，前端静态资源改动要清浏览器缓存。养成习惯：改完先想一下改的是哪一类，再决定要不要重启。判断服务是否重启成功，看日志里那行带版本号和端口号的启动记录就行。

5.3 一份可以直接抄的自查清单

环境搭完之后，按这个顺序过一遍，能挡掉大部分后续问题。

1. Terminal 里python -V，确认版本符合框架分支要求。
2. pip list里能看到框架的核心依赖，且版本是requirements.txt里要求的。
3. 项目树里核心代码目录的图标是源码根样式，不是普通文件夹。
4. Ctrl+点击能跳进框架核心代码，说明索引正常。
5. 运行配置的工作目录是项目根，不是子目录。
6. 配置文件里的addons_path末尾没有多余空格。
7. 调试模式启动一次，服务能起来，日志里没有 traceback。
8. 在任意一个 model 方法里打个断点，操作界面能停住。
9. 改一个视图字段的标签，刷新浏览器能看到变化。
10. 数据库账号有建库权限，能自己建一个新库测试。

这十条全过，环境这块基本可以画句号了。后面再遇到问题，基本都是业务代码本身的，不用再怀疑是环境。

5.4 我在实际配置中总结的几条经验

最后说几句心里话。第一，环境配置这件事不要图快，一次配对比后面天天修省事得多。我见过太多人为了赶进度随手装完就开始写，结果写了两周代码，一半时间花在重启和排查环境上。

第二，把配置过程和参数含义记下来。团队里新人入职照着你的记录走一遍就能起来，这比口头传授有效得多。配置文件里密码那几行记得排除出版本库，用模板文件加本地覆盖的方式管理。

第三，别迷信“一键安装脚本”。网上抄来的脚本你根本不知道它改了你系统的什么位置，出问题的时候连回滚都不知道往哪回。自己手敲一遍命令，每一步做了什么心里有数，这本身就是排查能力的一部分。

第四，调试器学会之后要主动用。很多人写代码靠 print 大法，改一次重启一次，一个简单问题排查半小时。断点加上表达式求值，同样的时间能多排查十几个场景。工具会用和不会用，差距是复利式的。

后续还可以这样扩展：把这套运行配置导出成团队共享模板，新人导入之后只改数据库和端口就能用；再进一步，把调试配置和数据库迁移脚本绑到一起，切换分支的时候自动准备对应的开发库。