拓冰网站定制 
前几天帮同事看一个卡了小半天的环境问题终端里翻来覆去就一行红字ModuleNotFoundError: No module named formatter。他的第一反应是“我代码里没写过 formatter 啊”于是去项目里全局搜索搜了个寂寞。问题不在业务代码里而在repo这个工具自己身上——它是个用 Python 写的启动脚本你系统里的 Python 升级到 3.10 之后标准库里的formatter模块被官方删掉了脚本一启动就找不到它当场躺平。这类报错特别有迷惑性命令行敲的是repo看起来像仓库或者镜像源的问题实际上是 Python 解释器和脚本版本在打架。这篇内容我打算把这件事从头到尾讲透repo是什么、为什么偏偏它中招、怎么三步定位、五种修法分别适合什么场景、哪些坑我亲手踩过。适合正在用repo管多仓库的 Android、嵌入式、大仓开发者也适合刚升级完 Python 环境发现一堆老脚本跑不起来的人。就算你从来不用repo只要你被ModuleNotFoundError折磨过里面的排查套路也是通用的。我会尽量说人话把每个命令为什么这么敲都交代清楚代码可以直接抄。1. 报错现场还原这一行错到底卡在哪一层1.1 repo 不是 git它只是 git 的“调度员”很多人第一次接触repo会以为它是另一个版本控制工具其实不是。repo本质上是一个 Python 写的脚本它干的事就是批量调度git你把几十上百个仓库的地址和分支写进一份 manifest XML 里repo sync一敲它按清单挨个去git clone/git fetch/git checkout保证所有仓库停在同一个版本组合上。项目本身没有自己的仓库后端所有数据最终还是存在每个子目录的.git里。这就解释了为什么这个报错这么“脆”repo的生命线是 Python 解释器解释器一变它就跟着遭殃。而git是 C 写的二进制程序跟 Python 版本毫无关系所以你会看到一个很诡异的现象——git能跑git clone也能跑唯独repo一敲就崩。这不是网络问题不是你 manifest 写错了更不是仓库权限问题纯粹是脚本和解释器不兼容。还有一点值得说清楚repo分发方式很特别它不是从包管理器装出来的一个“编译好的程序”而是一个自带引导逻辑的脚本。你从官方或者镜像站拿到的那个repo文件本质上是个“启动器”它第一次运行时会把自己对应的工具本体克隆到~/.repo/repo目录下之后每次执行都从那儿加载。所以同一个错误信息可能来自 PATH 上的启动器也可能来自~/.repo/repo里的本体这直接决定了你改哪个文件才有效——后面第 4 章会专门讲这个坑。1.2 formatter 是被 PEP 594 “带走”的不是被谁删错了formatter这个模块在 Python 里属于“上古遗物”。它诞生得很早用途是把文本按宽度做换行、缩进、对齐简单说就是一个非常原始的富文本排版器。问题是它从 Python 3.4 开始就被标记为废弃状态官方文档里明确写着“不建议新代码使用”理由也很直接功能太简陋实现太古老想维护又没人愿意接手社区里真正的排版需求早就被textwrap和shutil.get_terminal_size这类模块瓜分了。到了 Python 3.10formatter和parser一起被正式从标准库里移除。这个时间点很关键——2021 年 10 月发布的 3.10现在很多系统和发行版早就默认装上了你哪怕什么都没做只是跟着系统升级走了一遍环境也可能悄悄跨过了这条线。而repo的老版本里帮助信息的排版恰恰就是用formatter做的repo help这类命令要把子命令的说明文档按终端宽度折行输出早年就用了formatter.DumbWriter这套 API。新版repo早就换成别的写法了但老版本留在无数人机器上的那份拷贝不会自己更新。所以这条报错的本质一句话概括一个 2010 年代写的脚本遇上了 2021 年之后移除了老模块的解释器。这不属于谁写错了代码而是时间差造成的兼容债。1.3 为什么不是所有命令都报错偏偏某个子命令炸有个细节很多人没注意ModuleNotFoundError是运行时才触发的不是启动瞬间就炸。Python 的import语句写在哪个模块里只有执行到那个模块才会加载。老repo把formatter的导入放在帮助相关的子命令路径上所以你会看到很分裂的表现——repo init也许能跑通repo sync也许能跑通甚至repo --version都正常但一敲repo help或者某个会输出格式化文本的子命令立刻抛出ModuleNotFoundError: No module named formatter。这种“部分功能坏掉”的现象最误导人。你会本能地去怀疑出错的那个子命令对应的仓库、分支、manifest来回折腾半天。判断方法很简单看错误堆栈。堆栈里出现的是repo自己的路径比如/usr/bin/repo或~/.repo/repo/subcmds/help.py而不是你工程里的任何文件那就跟你的代码一点关系都没有直接往解释器版本这个方向查。顺带说一句如果你看到的是ModuleNotFoundError: No module named formatter但脚本路径指向的是你自己项目里的某个文件那性质完全不同——那是你的项目依赖了第三方formatter包但没装。判断标准永远是看堆栈里那个文件的归属别看报错信息本身。2. 三分钟定位确认是不是启动器太老2.1 四条命令锁定现场别急着改文件先花三分钟把现场信息收集齐。下面这几条命令建议按顺序敲一遍把输出贴到记事本里对比# 1. 当前 repo 到底在哪是哪个文件 which -a repo # 2. 这个文件用的是哪个解释器 head -n 1 $(which repo) # 3. 解释器版本以及 formatter 是否还在 python --version python -c import sys; print(sys.executable); print(sys.version) python -c import formatter 21 | tail -n 1 # 4. repo 自己的版本信息 repo --version第 3 条命令是整个诊断的核心。如果它输出ModuleNotFoundError: No module named formatter那就实锤了——你机器上这个解释器确实没有这个模块repo用同一个解释器跑必然报同样的错。反过来如果它能正常导入那说明你的repo用的可能不是这个解释器需要回到第 2 步看清楚 shebang 指向哪里。which -a repo加-a参数是有意为之。很多人机器上存在多份repo比如/usr/bin/repo一份、~/bin/repo一份、conda 环境里还有一份PATH 顺序决定了实际执行的是哪个。如果你只改了一份执行的是另一份那你会陷入“我明明改了怎么还报错”的自我怀疑。我见过最离谱的一台机器上有四份最后是靠which -a一次性抓出来的。2.2 版本对应关系对照表下面这张表是我根据实际遇到的情况整理的可以拿来做快速判断。核心逻辑是Python 版本决定formatter在不在repo启动器的年代决定它有没有调用formatter两边同时命中才会出问题。Python 版本formatter状态老版 repo 表现处理方向2.7存在正常运行已停止维护建议尽早迁走3.4 - 3.9存在但会打印废弃告警正常运行可能有告警刷屏可暂不动但别拖3.10 - 3.12已移除直接ModuleNotFoundError换启动器或换解释器3.12 及以上已移除且distutils也没了报错之外还可能连带pkg_resources相关问题换启动器顺手补构建工具3.13 及以上已移除并又清掉一批老模块老脚本大面积失效强烈建议整体升级工具链表里 3.12 那一行值得多看一眼。3.12 移除distutils之后很多老脚本会额外抛出No module named pkg_resources或者构建阶段的奇怪错误因为setuptools的旧版本依赖distutils。这两个问题经常一起出现修完formatter别以为就完事了跑一遍完整流程再说。2.3 别搞混另一个也叫 repo 的报错家族搜索这个报错的时候你一定会刷到一堆看起来很相关、但其实完全不是一回事的内容。最常见的就是Cannot find a valid baseurl for repo: base/7/x86_64和Cannot find a valid baseurl for repo: centos-sclo-rh/x86_64。这两个是包管理器在找软件源时报的错跟你手上的repo工具没有任何关系它们说的 “repo” 是软件仓库配置文件.repo结尾的那些文件的缩写。这一类问题的表现和解法完全是另一套包管理器读/etc/yum.repos.d/目录下的.repo文件里面写了baseurl或者mirrorlist如果地址失效、网络不可达、或者$releasever变量解析成了空值就会报Cannot find a valid baseurl。排查顺序是先ls /etc/yum.repos.d/看有几个源文件再确认里面的地址在当前环境下能不能访问最后清一下缓存重新生成。如果你是把某个源的.repo文件直接替换成自己维护的内容注意检查文件里的变量占位符有没有被正确展开。我把这两个家族列成一张表方便你一眼分辨报错关键词说的 “repo” 是什么归属领域首要排查方向No module named formatter多仓库管理工具 repoPython 脚本运行时解释器版本与脚本年代Cannot find a valid baseurl for repo软件仓库配置系统包管理源文件地址与网络可达性repo 恢复到拉版本默认状态多仓库工具的工作区状态版本控制工作区元数据与本地改动git 与 repo 仓库管理优劣势工具选型讨论工程效能仓库数量与版本一致性需求注意这三类问题里只有第一类和repo工具有关。别被搜索结果带跑偏先看你终端报错信息里的关键词再决定往哪个方向查。3. 五种修法按推荐程度从高到低排3.1 首选方案换掉启动器一劳永逸这是我最推荐的方案也是唯一一个“改完之后不用再惦记”的方案。原理很简单新版repo早就把formatter依赖去掉了你只要把手上那个老启动器换成新的问题从根上消失。而且新版启动器还顺带解决了一批其他兼容问题比如对 Python 3.12 的适配、对大仓库的并发调度优化等。操作分两步。第一步从一个在当前网络环境下能访问的镜像站点取最新的repo启动器覆盖掉 PATH 上那个旧的# 先备份别问为什么问就是踩过坑 cp $(which repo) ~/repo.bak.$(date %Y%m%d) # 从你能访问的镜像站下载最新启动器地址按你所在环境的镜像站替换 curl -fsSL -o ~/bin/repo 你的镜像站/git-repo/repo chmod ax ~/bin/repo第二步把~/bin放到 PATH 前面确保新启动器优先被找到然后清掉旧的本体让它重新拉取export PATH$HOME/bin:$PATH hash -r # 清掉 shell 的命令路径缓存这步经常被忘 rm -rf ~/.repo/repo # 只删工具本体不碰你的工作区第三步很关键验证一下repo --version python -c import sys; print(sys.version)repo --version输出的第一行会告诉你启动器版本和它识别到的 Python 版本。如果版本号是新的再随便敲一个之前会炸的子命令比如repo help看还会不会报formatter。跑通了就说明好了。提示hash -r这一步千万别省。部分 shell 会缓存命令的实际路径你换了文件但缓存还指向旧的表现出来就是“我明明换了怎么没用”。如果换完之后行为没变化先执行hash -r再不行就type -a repo看看到底执行的是哪个。3.2 次选方案把 shebang 指回一个还带 formatter 的解释器如果你的环境里确实保留着 Python 3.9 或者更老的版本又暂时不想动repo那就改启动器的第一行让脚本用那个老解释器跑。这个方案的优点是改一行就见效缺点是它是个“缓兵之计”——老解释器总会被淘汰你迟早得回来做 3.1。具体做法是打开启动器文件看第一行是什么。常见的有三种#!/usr/bin/env python → 跟着 PATH 上第一个 python 走最不可控 #!/usr/bin/python3 → 写死了系统 python3通常已经升到 3.10 以上 #!/usr/bin/python2.7 → 明确指定版本最不容易出意外推荐改成明确指定版本的形式别用env python。原因是env python的行为完全取决于当前 shell 的 PATH你在不同的终端、不同的虚拟环境里执行可能落到不同解释器上表现出来就是“同一个命令有时候好有时候坏”排查起来要命。# 假设你机器上有 python3.9 sed -i 1s|.*|#!/usr/bin/python3.9| ~/bin/repo head -n 1 ~/bin/repo改完之后记得同样执行hash -r再跑repo help验证。同时3.9 的解释器要确认真的能导入formatterpython3.9 -c import formatter; print(ok)能打印ok才算数。这里有个隐藏风险要提醒如果你用虚拟环境或者 conda 管理 Pythonenv python在某些激活状态下会指向环境里的解释器而那个环境的版本可能是 3.11。你改了系统上的启动器没用因为激活环境里的 PATH 优先级更高。遇到“改了没反应”的情况先command -v python看一眼实际用的是哪个。3.3 应急方案补一个 formatter 兼容层有些场景下你既没法换启动器比如团队统一从内部分发或者机器上的版本被管控也暂时上不了老解释器。这时候可以给解释器补一个最小可用的formatter模块把老脚本要用的那几个 API 顶上。这个方案我称之为“应急”因为它引入了自制代码后面维护的人如果不知情会觉得很迷惑。原理是利用 Python 的模块搜索顺序脚本执行时脚本所在目录会被放进sys.path的第一位。所以只要把formatter.py放在启动器同目录下导入时就会优先找到它。为了不污染系统目录更干净的做法是用PYTHONPATH指定一个专门的目录。先在某个位置建一个目录写好兼容模块# ~/.local/lib/repo_shim/formatter.py # 老 repo 在 Python 3.10 下的最小兼容层只覆盖它实际用到的 API import sys class AbstractWriter(object): 标准库 formatter.AbstractWriter 的极简替身接口保留行为置空。 def __init__(self): self._softspace 0 def reset(self): pass def flush_softspace(self): pass def push_alignment(self, align): pass def pop_alignment(self): pass def push_font(self, font): pass def pop_font(self): pass def push_margin(self, margin): pass def pop_margin(self): pass def push_style(self, *styles): pass def pop_style(self, n1): pass def send(self, data): raise NotImplementedError def newline(self): raise NotImplementedError def add_flowing_data(self, data): pass def add_literal_data(self, data): pass def add_label_data(self, fmt, counter, blanklineNone): pass class DumbWriter(AbstractWriter): 按最大列宽做朴素折行够用就好。 def __init__(self, fileNone, maxcol72): super(DumbWriter, self).__init__() self.file file or sys.stdout self.maxcol maxcol self.reset() def reset(self): self.col 0 self.atbreak 0 def send(self, data): col self.col atbreak self.atbreak out self.file.write for ch in data: if ch \n: out(\n) col 0 atbreak 0 elif ch in \t: if col and not atbreak: atbreak 1 else: out(ch) col 1 else: if atbreak: if col 1 self.maxcol: out(\n) col 0 else: out( ) col 1 atbreak 0 out(ch) col 1 self.col col self.atbreak atbreak def newline(self): self.file.write(\n) self.col 0 self.atbreak 0 def add_flowing_data(self, data): if data: self.send(data) def add_literal_data(self, data): if data: self.file.write(data) self.col 0 self.atbreak 0 class AbstractFormatter(object): 把格式化事件转发给 writer老代码里常见的组合用法。 def __init__(self, writer): self.writer writer def add_flowing_data(self, data): self.writer.add_flowing_data(data) def add_literal_data(self, data): self.writer.add_literal_data(data) def add_label_data(self, fmt, counter, blanklineNone): self.writer.add_label_data(fmt, counter, blankline) def flush_softspace(self): self.writer.flush_softspace() def push_alignment(self, align): self.writer.push_alignment(align) def pop_alignment(self): self.writer.pop_alignment() def push_font(self, font): self.writer.push_font(font) def pop_font(self): self.writer.pop_font() def push_margin(self, margin): self.writer.push_margin(margin) def pop_margin(self): self.writer.pop_margin() def push_style(self, *styles): self.writer.push_style(*styles) def pop_style(self, n1): self.writer.pop_style(n)然后在 shell 里挂上让repo执行时能找到export PYTHONPATH$HOME/.local/lib/repo_shim:$PYTHONPATH python -c import formatter; print(formatter.__file__)第二条命令必须输出你刚才建的那个文件路径而不是报错。如果输出的是别的位置说明PYTHONPATH没生效检查一下是不是写成了相对路径或者被别的环境变量覆盖了。注意这个兼容层是把行为“简化”了帮助文本的排版可能不如原版好看个别情况下会少几个空行。它的定位是让你先把仓库拉起来干活不是长期方案。上线前一定要换回 3.1 的正路别把一个自制兼容模块留在 CI 机器上半年后没人记得它是干嘛的。3.4 兜底方案直接给脚本打补丁如果你能接受改动工具本体最快的办法是直接把formatter的调用替换掉。这条路我只建议在临时调试、或者完全离线、拿不到新启动器的情况下用。先定位到底哪几处用到了grep -n formatter $(which repo) # 如果是多文件结构的本体路径换一下 grep -rn formatter ~/.repo/repo/ 2/dev/null | head -n 20如果只是import formatter加上一两处formatter.DumbWriter(...)的调用补丁量很小如果是整套AbstractFormatter的流水线用法那就不建议手改了改动面太大容易引入新问题。这种情况下更现实的做法是把repo本体降到一个跟当前解释器兼容的版本或者干脆按 3.5 的方式重置环境重新拉。3.5 环境重置把 repo 恢复到拉版本默认状态当你已经改乱了、或者不确定哪里被改过最省事的做法是把repo的工作区恢复到刚拉取时的默认状态。这里要分清楚哪些能删、哪些绝对不能删删错了你的本地改动就没了。~/.repo目录下的东西大致分三类工具本体repo子目录、清单仓库manifests等、你的工作区元数据projects、manifest.xml等。重建环境只需要动第一类后两类保留工作区就不会丢。# 1. 先看看里面有什么心里有数再动手 ls -la ~/.repo/ # 2. 只删工具本体让它重新拉一份干净的 rm -rf ~/.repo/repo # 3. 顺手清掉启动器的引导缓存不同版本位置略有差异 rm -rf ~/.repoconfig 2/dev/null # 4. 重新引导 cd 你的工作区根目录 repo init -u 你的 manifest 仓库地址 -b 分支执行repo init的时候启动器会重新从内置地址或者环境变量指定的地址把工具本体拉下来。如果你希望它从一个内网可达的地址拉可以在执行前设置环境变量把地址指向你环境里能访问的镜像这样能避免因为默认地址不可达而卡住export REPO_URL你环境里可达的 git-repo 镜像地址 repo init -u manifest 地址 -b 分支 --repo-revstable--repo-revstable这个参数值得加上。它让启动器拉取工具本体时选用标记为 stable 的版本相比跟随默认分支能少踩一些开发中的坑。如果你的团队有自己维护的稳定分支也可以把它写在这里。如果执行过程中出现校验相关的提示说明启动器在做签名验证而你的环境拿不到验证所需的材料这时候需要和团队确认内部规范不要随意跳过校验步骤。宁可多问一句也别在生产环境里关掉安全机制。4. 参数之外的细节坑基本都藏在这几处4.1 两份 repo改错一份等于白改前面反复提到“启动器”和“本体”两个概念这里展开说清楚因为这是最容易浪费时间的地方。启动器就是 PATH 上那个repo文件通常几 KB 到几十 KB是个引导脚本本体在~/.repo/repo/里是包含subcmds/、main.py等文件的一整个目录。执行repo命令时启动器先跑检查本体是否存在、版本是否匹配然后把自己交给本体执行。所以出错点可能在启动器里也可能在本体里。判断方法很直接看报错堆栈里的文件路径。路径是/usr/bin/repo或者你放的~/bin/repo就是启动器的问题路径是~/.repo/repo/subcmds/xxx.py就是本体的问题。搞清这一点再动手能省掉大量“改了没用”的困惑。多用户机器上还有个变体你用sudo跑过一次repo init~/.repo就变成了/root/.repo之后用普通用户跑repo读的是~/.repo两份状态各自独立表现出来就是“我明明初始化过为什么还提示没初始化”。确认方法是ls -la /root/.repo 2/dev/null和ls -la ~/.repo都看一眼。修法是统一用一个身份操作然后chown -R $(whoami):$(whoami) ~/.repo把权限捋顺。4.2 网络可达性卡住和报错要分开看这个报错本身跟网络无关但你在修的过程中一定会碰网络问题两者表现完全不同得分清。formatter报错是瞬间抛出、立刻退出的网络问题是长时间卡住、超时后才报错或者报的是连接相关的信息。如果你看到的是“卡了很久然后失败”那先别往解释器方向查。判断网络可达性的步骤很朴素先确认 manifest 仓库地址能不能通再确认工具本体的地址能不能通。这两个地址可以完全不同——manifest 是你自己项目的工具本体是repo自己的。很多人只测了前者忽略了后者结果在repo init引导阶段反复失败。# 测 manifest 仓库 git ls-remote 你的 manifest 仓库地址 HEAD # 测工具本体地址从环境变量或启动器里读出来 grep -n REPO_URL $(which repo) | head -n 5如果是公司内网环境通常会有内部镜像找运维或者带你的前辈要一份地址写进REPO_URL环境变量里比一个个试默认地址高效得多。把这条写进你的 shell 配置文件后面新机器初始化的时候能省不少事。4.3 多解释器共存时的优先级现在的开发机普遍同时装着系统 Python、brew 或者 conda 管理的 Python、还有项目虚拟环境里的 Python。repo启动器的 shebang 如果是#!/usr/bin/env python它的行为就完全取决于 PATH 的顺序而 PATH 又可能被各种激活脚本动态修改。一个很实际的建议给你的 shell 加一个自查函数遇到这类“明明改过却还报错”的情况一条命令看完所有关键信息。repo_diag() { echo repo 路径 ; which -a repo echo shebang ; head -n 1 $(which repo) echo python 解析 ; command -v python; command -v python3 echo 版本 ; python -c import sys; print(sys.version) echo formatter 可用性 python -c import formatter; print(formatter ok) 21 | tail -n 1 echo 本体目录 ; ls -d ~/.repo/repo 2/dev/null || echo 缺失需重新 init }把这个函数丢进~/.bashrc或者~/.zshrc下次再遇到类似问题敲一下repo_diag信息一次到位。这比在聊天窗口里跟同事来回问“你那 python 几版”高效太多了。4.4 权限与 sudo 混用这条其实是个通用经验但repo场景下格外突出因为它的状态目录在用户 home 下权限错了会表现出一堆莫名其妙的症状。典型的有repo sync中途报权限拒绝、某些目录创建失败、初始化到一半卡住。根因是repo会用当前用户身份去创建和修改~/.repo下的大量文件如果之前用sudo创建过一部分那部分文件属主是 root普通用户改不了于是流程走到那里就崩。排查方式是找一下目录里有没有 root 属主的文件find ~/.repo -user root -maxdepth 3 2/dev/null | head有输出就说明踩到了。修法是统属主然后重新执行一次初始化sudo chown -R $(id -u):$(id -g) ~/.repo注意不要养成“报错就加 sudo”的习惯。repo绝大多数操作都不需要提权加了反而会把问题从“明确的报错”变成“隐藏的权限错乱”。真遇到必须提权的场景先想清楚这个操作到底动了哪些系统目录。5. 常见问题速查与通用套路5.1 报错信息与处置方向对照表下面这张表覆盖了我这些年在这条线上遇到的问题也顺带把几类高频的ModuleNotFoundError变体一起列上了。判断逻辑统一是先看模块是谁在用再看解释器是谁在跑最后看环境有没有装。报错信息常见原因处置方向No module named formatterPython 3.10 移除该模块脚本年代过老换新启动器或指回老解释器No module named yaml解释器里没装 YAML 解析库在同一个解释器下安装对应库No module named pkg_resources构建工具缺失或新版本解释器自带环境不再预置补装打包工具检查虚拟环境No module named _cffi_backend底层扩展没编译成功只装了纯 Python 部分重装带二进制包确认平台匹配No module named numpy装到了另一个解释器或另一个虚拟环境用sys.executable确认实际解释器No module named cdsapi项目可选依赖未安装按项目说明装可选依赖别装错环境的No module named utils.features项目根目录不在模块搜索路径里或缺包标记文件从项目根目录启动检查包结构No module named opencv包名和导入名不一致装名字里带 opencv 的分发包导入名是 cv2表里第二行到第五行有个共同点它们几乎都是“装错了地方”。同一个项目在系统 Python 里装了一遍在 conda 环境里没装然后你在 conda 环境里跑就会报找不到。判断的最快办法是让程序自己告诉你它在用哪个解释器python -c import sys; print(sys.executable) python -c import sys; print(\n.join(sys.path))第一条输出实际解释器路径第二条输出模块搜索路径。有了这两条绝大多数No module named类问题都能在五分钟内定位。5.2 ModuleNotFoundError 通用排查四步法这套流程我从早期的瞎试慢慢打磨成了固定动作现在遇到任何No module named都按这个顺序走基本不会绕远路。第一步看堆栈里的文件归属。是你自己的代码、是第三方库、还是某个工具脚本归属决定了责任方也决定了你能不能直接改。第二步确认执行时用的是哪个解释器。用sys.executable打印别靠猜。很多人以为敲了python就是系统 Python实际上可能是虚拟环境或者某个工具链注入的解释器。第三步确认sys.path里有没有那个模块应该在的位置。用上面那行命令把路径全打出来看看目标目录在不在。不在就说明环境隔离或路径配置有问题而不是“没装”。第四步确认模块是否真的安装以及安装的名字和导入的名字是否一致。这一条特别容易被忽略比如有些分发包安装名和导入名完全不同安装名带前缀导入名却是另一个短名字。装的时候要用安装名代码里导入要用导入名两者对不上就会误判成“没装”。把这四步写完你会发现绝大多数这类报错根本不用搜索引擎自己就能定位。这也是我为什么一直强调要看堆栈、要看解释器路径——这两个信息拿到了问题基本就解决一半了。5.3 我的避坑清单几条纯经验文档里不会写但都是实打实影响效率的给机器上所有repo相关的东西做个记录包括启动器路径、版本号、本体路径、REPO_URL的设置位置。新同事入职或者机器重装时这份记录能省下半天时间。改任何工具脚本前先备份命名带上日期。不是为了优雅是为了在改坏之后能三秒钟回滚而不是重新回忆自己改了什么。把环境自查写成脚本。前面那个repo_diag函数就是例子它能把你从“凭记忆逐条敲命令”里解放出来也方便截图发给别人求助。不要把兼容层、临时补丁这类东西带进 CI。CI 环境更干净也更难过期临时方案在本地跑得通不代表在 CI 上跑得通。该升级工具链就升级别让技术债在流水线上爆雷。记录你每次遇到的报错的完整信息包括命令、完整堆栈、解释器版本、解决方式。一年之后你大概率会再次遇到同一个问题而那时候你不会记得当时是怎么解决的。6. 顺带聊聊git 和 repo 到底该怎么选6.1 repo 的真实优势在哪聊完报错回到工具本身。经常有人问要不要上repo我的判断标准很简单看你的仓库数量以及你是否需要“版本组合一致性”这个能力。repo最核心的价值就是 manifest 那层抽象。它把“哪个仓库、哪个分支、哪个提交”写进一份 XML所有人按同一份清单同步天然保证大家的代码组合是一致的。这对那种一个产品拆成几十上百个仓库的工程来说是刚需——你要手工维护这么多仓库的版本对应关系出错概率极高而且排查成本巨大。第二个优势是批量操作。repo forall能在所有仓库里跑同一条命令比如批量打标签、批量看状态、批量执行格式化这在多仓库场景下省下的时间非常可观。用git手工遍历得先维护一份仓库列表再写循环还得处理各种异常投入产出比不划算。第三个优势是把清单本身也纳入版本控制。manifest 仓库自己是个 git 仓库谁改了清单、什么时候改的、为什么改轨迹清清楚楚。出了问题可以二分定位回滚也有依据。这一点在多人协作、多分支并行的团队里价值极高。6.2 什么时候别用 repo反面同样要说清楚不然容易过度设计。如果你的项目就是一个仓库或者最多三五个仓库那引入repo基本是给自己找麻烦多一层工具就多一层依赖出问题的时候多了排查路径新人上手也要多学一套命令收益完全比不上成本。还有一种情况是要慎重的团队的技术栈以 Python 为主但机器上 Python 版本管理比较随意。因为repo是 Python 工具解释器升级会直接影响到它就像这次这个formatter问题。真要在大团队里长期用建议把工具版本、解释器版本这类信息写进团队的环境说明文档里新人按文档配一遍能规避掉大量环境差异带来的问题。替代方案上仓库数量少可以用子模块之类的 git 原生命令或者用包管理器把公共部分发成依赖仓库数量多且追求极致一致性也可以考虑单体仓库的工程实践把工具链和维护成本压在一个仓库里。选择本身就取决于你的团队规模、仓库数量、以及你能接受多少维护成本没有通用答案。提示与其纠结工具选型不如先把环境的版本基线定下来。工具换来换去最终卡住进度的往往是“你这台机器上的解释器跟别人不一样”这种小事。定基线这件事花不了多少时间但能省掉无数次今天这种排查。我自己的做法是在所有涉及repo的机器上把repo_diag和一份环境说明放在同一个位置谁遇到问题先跑一遍自查跑完再看文档。这套习惯养成之后团队里因为环境不一致而卡住的次数明显少了。至于formatter这个报错我现在看到它的第一反应已经不是去搜怎么修而是直接换启动器——因为修过太多次了每修一次都在心里骂一句这个模块为什么不早点被清掉。 repo 报 formatter 缺失：Python 3.10 兼容修复
前几天帮同事看一个卡了小半天的环境问题终端里翻来覆去就一行红字ModuleNotFoundError: No module named formatter。他的第一反应是“我代码里没写过 formatter 啊”于是去项目里全局搜索搜了个寂寞。问题不在业务代码里而在repo这个工具自己身上——它是个用 Python 写的启动脚本你系统里的 Python 升级到 3.10 之后标准库里的formatter模块被官方删掉了脚本一启动就找不到它当场躺平。这类报错特别有迷惑性命令行敲的是repo看起来像仓库或者镜像源的问题实际上是 Python 解释器和脚本版本在打架。这篇内容我打算把这件事从头到尾讲透repo是什么、为什么偏偏它中招、怎么三步定位、五种修法分别适合什么场景、哪些坑我亲手踩过。适合正在用repo管多仓库的 Android、嵌入式、大仓开发者也适合刚升级完 Python 环境发现一堆老脚本跑不起来的人。就算你从来不用repo只要你被ModuleNotFoundError折磨过里面的排查套路也是通用的。我会尽量说人话把每个命令为什么这么敲都交代清楚代码可以直接抄。1. 报错现场还原这一行错到底卡在哪一层1.1 repo 不是 git它只是 git 的“调度员”很多人第一次接触repo会以为它是另一个版本控制工具其实不是。repo本质上是一个 Python 写的脚本它干的事就是批量调度git你把几十上百个仓库的地址和分支写进一份 manifest XML 里repo sync一敲它按清单挨个去git clone/git fetch/git checkout保证所有仓库停在同一个版本组合上。项目本身没有自己的仓库后端所有数据最终还是存在每个子目录的.git里。这就解释了为什么这个报错这么“脆”repo的生命线是 Python 解释器解释器一变它就跟着遭殃。而git是 C 写的二进制程序跟 Python 版本毫无关系所以你会看到一个很诡异的现象——git能跑git clone也能跑唯独repo一敲就崩。这不是网络问题不是你 manifest 写错了更不是仓库权限问题纯粹是脚本和解释器不兼容。还有一点值得说清楚repo分发方式很特别它不是从包管理器装出来的一个“编译好的程序”而是一个自带引导逻辑的脚本。你从官方或者镜像站拿到的那个repo文件本质上是个“启动器”它第一次运行时会把自己对应的工具本体克隆到~/.repo/repo目录下之后每次执行都从那儿加载。所以同一个错误信息可能来自 PATH 上的启动器也可能来自~/.repo/repo里的本体这直接决定了你改哪个文件才有效——后面第 4 章会专门讲这个坑。1.2 formatter 是被 PEP 594 “带走”的不是被谁删错了formatter这个模块在 Python 里属于“上古遗物”。它诞生得很早用途是把文本按宽度做换行、缩进、对齐简单说就是一个非常原始的富文本排版器。问题是它从 Python 3.4 开始就被标记为废弃状态官方文档里明确写着“不建议新代码使用”理由也很直接功能太简陋实现太古老想维护又没人愿意接手社区里真正的排版需求早就被textwrap和shutil.get_terminal_size这类模块瓜分了。到了 Python 3.10formatter和parser一起被正式从标准库里移除。这个时间点很关键——2021 年 10 月发布的 3.10现在很多系统和发行版早就默认装上了你哪怕什么都没做只是跟着系统升级走了一遍环境也可能悄悄跨过了这条线。而repo的老版本里帮助信息的排版恰恰就是用formatter做的repo help这类命令要把子命令的说明文档按终端宽度折行输出早年就用了formatter.DumbWriter这套 API。新版repo早就换成别的写法了但老版本留在无数人机器上的那份拷贝不会自己更新。所以这条报错的本质一句话概括一个 2010 年代写的脚本遇上了 2021 年之后移除了老模块的解释器。这不属于谁写错了代码而是时间差造成的兼容债。1.3 为什么不是所有命令都报错偏偏某个子命令炸有个细节很多人没注意ModuleNotFoundError是运行时才触发的不是启动瞬间就炸。Python 的import语句写在哪个模块里只有执行到那个模块才会加载。老repo把formatter的导入放在帮助相关的子命令路径上所以你会看到很分裂的表现——repo init也许能跑通repo sync也许能跑通甚至repo --version都正常但一敲repo help或者某个会输出格式化文本的子命令立刻抛出ModuleNotFoundError: No module named formatter。这种“部分功能坏掉”的现象最误导人。你会本能地去怀疑出错的那个子命令对应的仓库、分支、manifest来回折腾半天。判断方法很简单看错误堆栈。堆栈里出现的是repo自己的路径比如/usr/bin/repo或~/.repo/repo/subcmds/help.py而不是你工程里的任何文件那就跟你的代码一点关系都没有直接往解释器版本这个方向查。顺带说一句如果你看到的是ModuleNotFoundError: No module named formatter但脚本路径指向的是你自己项目里的某个文件那性质完全不同——那是你的项目依赖了第三方formatter包但没装。判断标准永远是看堆栈里那个文件的归属别看报错信息本身。2. 三分钟定位确认是不是启动器太老2.1 四条命令锁定现场别急着改文件先花三分钟把现场信息收集齐。下面这几条命令建议按顺序敲一遍把输出贴到记事本里对比# 1. 当前 repo 到底在哪是哪个文件 which -a repo # 2. 这个文件用的是哪个解释器 head -n 1 $(which repo) # 3. 解释器版本以及 formatter 是否还在 python --version python -c import sys; print(sys.executable); print(sys.version) python -c import formatter 21 | tail -n 1 # 4. repo 自己的版本信息 repo --version第 3 条命令是整个诊断的核心。如果它输出ModuleNotFoundError: No module named formatter那就实锤了——你机器上这个解释器确实没有这个模块repo用同一个解释器跑必然报同样的错。反过来如果它能正常导入那说明你的repo用的可能不是这个解释器需要回到第 2 步看清楚 shebang 指向哪里。which -a repo加-a参数是有意为之。很多人机器上存在多份repo比如/usr/bin/repo一份、~/bin/repo一份、conda 环境里还有一份PATH 顺序决定了实际执行的是哪个。如果你只改了一份执行的是另一份那你会陷入“我明明改了怎么还报错”的自我怀疑。我见过最离谱的一台机器上有四份最后是靠which -a一次性抓出来的。2.2 版本对应关系对照表下面这张表是我根据实际遇到的情况整理的可以拿来做快速判断。核心逻辑是Python 版本决定formatter在不在repo启动器的年代决定它有没有调用formatter两边同时命中才会出问题。Python 版本formatter状态老版 repo 表现处理方向2.7存在正常运行已停止维护建议尽早迁走3.4 - 3.9存在但会打印废弃告警正常运行可能有告警刷屏可暂不动但别拖3.10 - 3.12已移除直接ModuleNotFoundError换启动器或换解释器3.12 及以上已移除且distutils也没了报错之外还可能连带pkg_resources相关问题换启动器顺手补构建工具3.13 及以上已移除并又清掉一批老模块老脚本大面积失效强烈建议整体升级工具链表里 3.12 那一行值得多看一眼。3.12 移除distutils之后很多老脚本会额外抛出No module named pkg_resources或者构建阶段的奇怪错误因为setuptools的旧版本依赖distutils。这两个问题经常一起出现修完formatter别以为就完事了跑一遍完整流程再说。2.3 别搞混另一个也叫 repo 的报错家族搜索这个报错的时候你一定会刷到一堆看起来很相关、但其实完全不是一回事的内容。最常见的就是Cannot find a valid baseurl for repo: base/7/x86_64和Cannot find a valid baseurl for repo: centos-sclo-rh/x86_64。这两个是包管理器在找软件源时报的错跟你手上的repo工具没有任何关系它们说的 “repo” 是软件仓库配置文件.repo结尾的那些文件的缩写。这一类问题的表现和解法完全是另一套包管理器读/etc/yum.repos.d/目录下的.repo文件里面写了baseurl或者mirrorlist如果地址失效、网络不可达、或者$releasever变量解析成了空值就会报Cannot find a valid baseurl。排查顺序是先ls /etc/yum.repos.d/看有几个源文件再确认里面的地址在当前环境下能不能访问最后清一下缓存重新生成。如果你是把某个源的.repo文件直接替换成自己维护的内容注意检查文件里的变量占位符有没有被正确展开。我把这两个家族列成一张表方便你一眼分辨报错关键词说的 “repo” 是什么归属领域首要排查方向No module named formatter多仓库管理工具 repoPython 脚本运行时解释器版本与脚本年代Cannot find a valid baseurl for repo软件仓库配置系统包管理源文件地址与网络可达性repo 恢复到拉版本默认状态多仓库工具的工作区状态版本控制工作区元数据与本地改动git 与 repo 仓库管理优劣势工具选型讨论工程效能仓库数量与版本一致性需求注意这三类问题里只有第一类和repo工具有关。别被搜索结果带跑偏先看你终端报错信息里的关键词再决定往哪个方向查。3. 五种修法按推荐程度从高到低排3.1 首选方案换掉启动器一劳永逸这是我最推荐的方案也是唯一一个“改完之后不用再惦记”的方案。原理很简单新版repo早就把formatter依赖去掉了你只要把手上那个老启动器换成新的问题从根上消失。而且新版启动器还顺带解决了一批其他兼容问题比如对 Python 3.12 的适配、对大仓库的并发调度优化等。操作分两步。第一步从一个在当前网络环境下能访问的镜像站点取最新的repo启动器覆盖掉 PATH 上那个旧的# 先备份别问为什么问就是踩过坑 cp $(which repo) ~/repo.bak.$(date %Y%m%d) # 从你能访问的镜像站下载最新启动器地址按你所在环境的镜像站替换 curl -fsSL -o ~/bin/repo 你的镜像站/git-repo/repo chmod ax ~/bin/repo第二步把~/bin放到 PATH 前面确保新启动器优先被找到然后清掉旧的本体让它重新拉取export PATH$HOME/bin:$PATH hash -r # 清掉 shell 的命令路径缓存这步经常被忘 rm -rf ~/.repo/repo # 只删工具本体不碰你的工作区第三步很关键验证一下repo --version python -c import sys; print(sys.version)repo --version输出的第一行会告诉你启动器版本和它识别到的 Python 版本。如果版本号是新的再随便敲一个之前会炸的子命令比如repo help看还会不会报formatter。跑通了就说明好了。提示hash -r这一步千万别省。部分 shell 会缓存命令的实际路径你换了文件但缓存还指向旧的表现出来就是“我明明换了怎么没用”。如果换完之后行为没变化先执行hash -r再不行就type -a repo看看到底执行的是哪个。3.2 次选方案把 shebang 指回一个还带 formatter 的解释器如果你的环境里确实保留着 Python 3.9 或者更老的版本又暂时不想动repo那就改启动器的第一行让脚本用那个老解释器跑。这个方案的优点是改一行就见效缺点是它是个“缓兵之计”——老解释器总会被淘汰你迟早得回来做 3.1。具体做法是打开启动器文件看第一行是什么。常见的有三种#!/usr/bin/env python → 跟着 PATH 上第一个 python 走最不可控 #!/usr/bin/python3 → 写死了系统 python3通常已经升到 3.10 以上 #!/usr/bin/python2.7 → 明确指定版本最不容易出意外推荐改成明确指定版本的形式别用env python。原因是env python的行为完全取决于当前 shell 的 PATH你在不同的终端、不同的虚拟环境里执行可能落到不同解释器上表现出来就是“同一个命令有时候好有时候坏”排查起来要命。# 假设你机器上有 python3.9 sed -i 1s|.*|#!/usr/bin/python3.9| ~/bin/repo head -n 1 ~/bin/repo改完之后记得同样执行hash -r再跑repo help验证。同时3.9 的解释器要确认真的能导入formatterpython3.9 -c import formatter; print(ok)能打印ok才算数。这里有个隐藏风险要提醒如果你用虚拟环境或者 conda 管理 Pythonenv python在某些激活状态下会指向环境里的解释器而那个环境的版本可能是 3.11。你改了系统上的启动器没用因为激活环境里的 PATH 优先级更高。遇到“改了没反应”的情况先command -v python看一眼实际用的是哪个。3.3 应急方案补一个 formatter 兼容层有些场景下你既没法换启动器比如团队统一从内部分发或者机器上的版本被管控也暂时上不了老解释器。这时候可以给解释器补一个最小可用的formatter模块把老脚本要用的那几个 API 顶上。这个方案我称之为“应急”因为它引入了自制代码后面维护的人如果不知情会觉得很迷惑。原理是利用 Python 的模块搜索顺序脚本执行时脚本所在目录会被放进sys.path的第一位。所以只要把formatter.py放在启动器同目录下导入时就会优先找到它。为了不污染系统目录更干净的做法是用PYTHONPATH指定一个专门的目录。先在某个位置建一个目录写好兼容模块# ~/.local/lib/repo_shim/formatter.py # 老 repo 在 Python 3.10 下的最小兼容层只覆盖它实际用到的 API import sys class AbstractWriter(object): 标准库 formatter.AbstractWriter 的极简替身接口保留行为置空。 def __init__(self): self._softspace 0 def reset(self): pass def flush_softspace(self): pass def push_alignment(self, align): pass def pop_alignment(self): pass def push_font(self, font): pass def pop_font(self): pass def push_margin(self, margin): pass def pop_margin(self): pass def push_style(self, *styles): pass def pop_style(self, n1): pass def send(self, data): raise NotImplementedError def newline(self): raise NotImplementedError def add_flowing_data(self, data): pass def add_literal_data(self, data): pass def add_label_data(self, fmt, counter, blanklineNone): pass class DumbWriter(AbstractWriter): 按最大列宽做朴素折行够用就好。 def __init__(self, fileNone, maxcol72): super(DumbWriter, self).__init__() self.file file or sys.stdout self.maxcol maxcol self.reset() def reset(self): self.col 0 self.atbreak 0 def send(self, data): col self.col atbreak self.atbreak out self.file.write for ch in data: if ch \n: out(\n) col 0 atbreak 0 elif ch in \t: if col and not atbreak: atbreak 1 else: out(ch) col 1 else: if atbreak: if col 1 self.maxcol: out(\n) col 0 else: out( ) col 1 atbreak 0 out(ch) col 1 self.col col self.atbreak atbreak def newline(self): self.file.write(\n) self.col 0 self.atbreak 0 def add_flowing_data(self, data): if data: self.send(data) def add_literal_data(self, data): if data: self.file.write(data) self.col 0 self.atbreak 0 class AbstractFormatter(object): 把格式化事件转发给 writer老代码里常见的组合用法。 def __init__(self, writer): self.writer writer def add_flowing_data(self, data): self.writer.add_flowing_data(data) def add_literal_data(self, data): self.writer.add_literal_data(data) def add_label_data(self, fmt, counter, blanklineNone): self.writer.add_label_data(fmt, counter, blankline) def flush_softspace(self): self.writer.flush_softspace() def push_alignment(self, align): self.writer.push_alignment(align) def pop_alignment(self): self.writer.pop_alignment() def push_font(self, font): self.writer.push_font(font) def pop_font(self): self.writer.pop_font() def push_margin(self, margin): self.writer.push_margin(margin) def pop_margin(self): self.writer.pop_margin() def push_style(self, *styles): self.writer.push_style(*styles) def pop_style(self, n1): self.writer.pop_style(n)然后在 shell 里挂上让repo执行时能找到export PYTHONPATH$HOME/.local/lib/repo_shim:$PYTHONPATH python -c import formatter; print(formatter.__file__)第二条命令必须输出你刚才建的那个文件路径而不是报错。如果输出的是别的位置说明PYTHONPATH没生效检查一下是不是写成了相对路径或者被别的环境变量覆盖了。注意这个兼容层是把行为“简化”了帮助文本的排版可能不如原版好看个别情况下会少几个空行。它的定位是让你先把仓库拉起来干活不是长期方案。上线前一定要换回 3.1 的正路别把一个自制兼容模块留在 CI 机器上半年后没人记得它是干嘛的。3.4 兜底方案直接给脚本打补丁如果你能接受改动工具本体最快的办法是直接把formatter的调用替换掉。这条路我只建议在临时调试、或者完全离线、拿不到新启动器的情况下用。先定位到底哪几处用到了grep -n formatter $(which repo) # 如果是多文件结构的本体路径换一下 grep -rn formatter ~/.repo/repo/ 2/dev/null | head -n 20如果只是import formatter加上一两处formatter.DumbWriter(...)的调用补丁量很小如果是整套AbstractFormatter的流水线用法那就不建议手改了改动面太大容易引入新问题。这种情况下更现实的做法是把repo本体降到一个跟当前解释器兼容的版本或者干脆按 3.5 的方式重置环境重新拉。3.5 环境重置把 repo 恢复到拉版本默认状态当你已经改乱了、或者不确定哪里被改过最省事的做法是把repo的工作区恢复到刚拉取时的默认状态。这里要分清楚哪些能删、哪些绝对不能删删错了你的本地改动就没了。~/.repo目录下的东西大致分三类工具本体repo子目录、清单仓库manifests等、你的工作区元数据projects、manifest.xml等。重建环境只需要动第一类后两类保留工作区就不会丢。# 1. 先看看里面有什么心里有数再动手 ls -la ~/.repo/ # 2. 只删工具本体让它重新拉一份干净的 rm -rf ~/.repo/repo # 3. 顺手清掉启动器的引导缓存不同版本位置略有差异 rm -rf ~/.repoconfig 2/dev/null # 4. 重新引导 cd 你的工作区根目录 repo init -u 你的 manifest 仓库地址 -b 分支执行repo init的时候启动器会重新从内置地址或者环境变量指定的地址把工具本体拉下来。如果你希望它从一个内网可达的地址拉可以在执行前设置环境变量把地址指向你环境里能访问的镜像这样能避免因为默认地址不可达而卡住export REPO_URL你环境里可达的 git-repo 镜像地址 repo init -u manifest 地址 -b 分支 --repo-revstable--repo-revstable这个参数值得加上。它让启动器拉取工具本体时选用标记为 stable 的版本相比跟随默认分支能少踩一些开发中的坑。如果你的团队有自己维护的稳定分支也可以把它写在这里。如果执行过程中出现校验相关的提示说明启动器在做签名验证而你的环境拿不到验证所需的材料这时候需要和团队确认内部规范不要随意跳过校验步骤。宁可多问一句也别在生产环境里关掉安全机制。4. 参数之外的细节坑基本都藏在这几处4.1 两份 repo改错一份等于白改前面反复提到“启动器”和“本体”两个概念这里展开说清楚因为这是最容易浪费时间的地方。启动器就是 PATH 上那个repo文件通常几 KB 到几十 KB是个引导脚本本体在~/.repo/repo/里是包含subcmds/、main.py等文件的一整个目录。执行repo命令时启动器先跑检查本体是否存在、版本是否匹配然后把自己交给本体执行。所以出错点可能在启动器里也可能在本体里。判断方法很直接看报错堆栈里的文件路径。路径是/usr/bin/repo或者你放的~/bin/repo就是启动器的问题路径是~/.repo/repo/subcmds/xxx.py就是本体的问题。搞清这一点再动手能省掉大量“改了没用”的困惑。多用户机器上还有个变体你用sudo跑过一次repo init~/.repo就变成了/root/.repo之后用普通用户跑repo读的是~/.repo两份状态各自独立表现出来就是“我明明初始化过为什么还提示没初始化”。确认方法是ls -la /root/.repo 2/dev/null和ls -la ~/.repo都看一眼。修法是统一用一个身份操作然后chown -R $(whoami):$(whoami) ~/.repo把权限捋顺。4.2 网络可达性卡住和报错要分开看这个报错本身跟网络无关但你在修的过程中一定会碰网络问题两者表现完全不同得分清。formatter报错是瞬间抛出、立刻退出的网络问题是长时间卡住、超时后才报错或者报的是连接相关的信息。如果你看到的是“卡了很久然后失败”那先别往解释器方向查。判断网络可达性的步骤很朴素先确认 manifest 仓库地址能不能通再确认工具本体的地址能不能通。这两个地址可以完全不同——manifest 是你自己项目的工具本体是repo自己的。很多人只测了前者忽略了后者结果在repo init引导阶段反复失败。# 测 manifest 仓库 git ls-remote 你的 manifest 仓库地址 HEAD # 测工具本体地址从环境变量或启动器里读出来 grep -n REPO_URL $(which repo) | head -n 5如果是公司内网环境通常会有内部镜像找运维或者带你的前辈要一份地址写进REPO_URL环境变量里比一个个试默认地址高效得多。把这条写进你的 shell 配置文件后面新机器初始化的时候能省不少事。4.3 多解释器共存时的优先级现在的开发机普遍同时装着系统 Python、brew 或者 conda 管理的 Python、还有项目虚拟环境里的 Python。repo启动器的 shebang 如果是#!/usr/bin/env python它的行为就完全取决于 PATH 的顺序而 PATH 又可能被各种激活脚本动态修改。一个很实际的建议给你的 shell 加一个自查函数遇到这类“明明改过却还报错”的情况一条命令看完所有关键信息。repo_diag() { echo repo 路径 ; which -a repo echo shebang ; head -n 1 $(which repo) echo python 解析 ; command -v python; command -v python3 echo 版本 ; python -c import sys; print(sys.version) echo formatter 可用性 python -c import formatter; print(formatter ok) 21 | tail -n 1 echo 本体目录 ; ls -d ~/.repo/repo 2/dev/null || echo 缺失需重新 init }把这个函数丢进~/.bashrc或者~/.zshrc下次再遇到类似问题敲一下repo_diag信息一次到位。这比在聊天窗口里跟同事来回问“你那 python 几版”高效太多了。4.4 权限与 sudo 混用这条其实是个通用经验但repo场景下格外突出因为它的状态目录在用户 home 下权限错了会表现出一堆莫名其妙的症状。典型的有repo sync中途报权限拒绝、某些目录创建失败、初始化到一半卡住。根因是repo会用当前用户身份去创建和修改~/.repo下的大量文件如果之前用sudo创建过一部分那部分文件属主是 root普通用户改不了于是流程走到那里就崩。排查方式是找一下目录里有没有 root 属主的文件find ~/.repo -user root -maxdepth 3 2/dev/null | head有输出就说明踩到了。修法是统属主然后重新执行一次初始化sudo chown -R $(id -u):$(id -g) ~/.repo注意不要养成“报错就加 sudo”的习惯。repo绝大多数操作都不需要提权加了反而会把问题从“明确的报错”变成“隐藏的权限错乱”。真遇到必须提权的场景先想清楚这个操作到底动了哪些系统目录。5. 常见问题速查与通用套路5.1 报错信息与处置方向对照表下面这张表覆盖了我这些年在这条线上遇到的问题也顺带把几类高频的ModuleNotFoundError变体一起列上了。判断逻辑统一是先看模块是谁在用再看解释器是谁在跑最后看环境有没有装。报错信息常见原因处置方向No module named formatterPython 3.10 移除该模块脚本年代过老换新启动器或指回老解释器No module named yaml解释器里没装 YAML 解析库在同一个解释器下安装对应库No module named pkg_resources构建工具缺失或新版本解释器自带环境不再预置补装打包工具检查虚拟环境No module named _cffi_backend底层扩展没编译成功只装了纯 Python 部分重装带二进制包确认平台匹配No module named numpy装到了另一个解释器或另一个虚拟环境用sys.executable确认实际解释器No module named cdsapi项目可选依赖未安装按项目说明装可选依赖别装错环境的No module named utils.features项目根目录不在模块搜索路径里或缺包标记文件从项目根目录启动检查包结构No module named opencv包名和导入名不一致装名字里带 opencv 的分发包导入名是 cv2表里第二行到第五行有个共同点它们几乎都是“装错了地方”。同一个项目在系统 Python 里装了一遍在 conda 环境里没装然后你在 conda 环境里跑就会报找不到。判断的最快办法是让程序自己告诉你它在用哪个解释器python -c import sys; print(sys.executable) python -c import sys; print(\n.join(sys.path))第一条输出实际解释器路径第二条输出模块搜索路径。有了这两条绝大多数No module named类问题都能在五分钟内定位。5.2 ModuleNotFoundError 通用排查四步法这套流程我从早期的瞎试慢慢打磨成了固定动作现在遇到任何No module named都按这个顺序走基本不会绕远路。第一步看堆栈里的文件归属。是你自己的代码、是第三方库、还是某个工具脚本归属决定了责任方也决定了你能不能直接改。第二步确认执行时用的是哪个解释器。用sys.executable打印别靠猜。很多人以为敲了python就是系统 Python实际上可能是虚拟环境或者某个工具链注入的解释器。第三步确认sys.path里有没有那个模块应该在的位置。用上面那行命令把路径全打出来看看目标目录在不在。不在就说明环境隔离或路径配置有问题而不是“没装”。第四步确认模块是否真的安装以及安装的名字和导入的名字是否一致。这一条特别容易被忽略比如有些分发包安装名和导入名完全不同安装名带前缀导入名却是另一个短名字。装的时候要用安装名代码里导入要用导入名两者对不上就会误判成“没装”。把这四步写完你会发现绝大多数这类报错根本不用搜索引擎自己就能定位。这也是我为什么一直强调要看堆栈、要看解释器路径——这两个信息拿到了问题基本就解决一半了。5.3 我的避坑清单几条纯经验文档里不会写但都是实打实影响效率的给机器上所有repo相关的东西做个记录包括启动器路径、版本号、本体路径、REPO_URL的设置位置。新同事入职或者机器重装时这份记录能省下半天时间。改任何工具脚本前先备份命名带上日期。不是为了优雅是为了在改坏之后能三秒钟回滚而不是重新回忆自己改了什么。把环境自查写成脚本。前面那个repo_diag函数就是例子它能把你从“凭记忆逐条敲命令”里解放出来也方便截图发给别人求助。不要把兼容层、临时补丁这类东西带进 CI。CI 环境更干净也更难过期临时方案在本地跑得通不代表在 CI 上跑得通。该升级工具链就升级别让技术债在流水线上爆雷。记录你每次遇到的报错的完整信息包括命令、完整堆栈、解释器版本、解决方式。一年之后你大概率会再次遇到同一个问题而那时候你不会记得当时是怎么解决的。6. 顺带聊聊git 和 repo 到底该怎么选6.1 repo 的真实优势在哪聊完报错回到工具本身。经常有人问要不要上repo我的判断标准很简单看你的仓库数量以及你是否需要“版本组合一致性”这个能力。repo最核心的价值就是 manifest 那层抽象。它把“哪个仓库、哪个分支、哪个提交”写进一份 XML所有人按同一份清单同步天然保证大家的代码组合是一致的。这对那种一个产品拆成几十上百个仓库的工程来说是刚需——你要手工维护这么多仓库的版本对应关系出错概率极高而且排查成本巨大。第二个优势是批量操作。repo forall能在所有仓库里跑同一条命令比如批量打标签、批量看状态、批量执行格式化这在多仓库场景下省下的时间非常可观。用git手工遍历得先维护一份仓库列表再写循环还得处理各种异常投入产出比不划算。第三个优势是把清单本身也纳入版本控制。manifest 仓库自己是个 git 仓库谁改了清单、什么时候改的、为什么改轨迹清清楚楚。出了问题可以二分定位回滚也有依据。这一点在多人协作、多分支并行的团队里价值极高。6.2 什么时候别用 repo反面同样要说清楚不然容易过度设计。如果你的项目就是一个仓库或者最多三五个仓库那引入repo基本是给自己找麻烦多一层工具就多一层依赖出问题的时候多了排查路径新人上手也要多学一套命令收益完全比不上成本。还有一种情况是要慎重的团队的技术栈以 Python 为主但机器上 Python 版本管理比较随意。因为repo是 Python 工具解释器升级会直接影响到它就像这次这个formatter问题。真要在大团队里长期用建议把工具版本、解释器版本这类信息写进团队的环境说明文档里新人按文档配一遍能规避掉大量环境差异带来的问题。替代方案上仓库数量少可以用子模块之类的 git 原生命令或者用包管理器把公共部分发成依赖仓库数量多且追求极致一致性也可以考虑单体仓库的工程实践把工具链和维护成本压在一个仓库里。选择本身就取决于你的团队规模、仓库数量、以及你能接受多少维护成本没有通用答案。提示与其纠结工具选型不如先把环境的版本基线定下来。工具换来换去最终卡住进度的往往是“你这台机器上的解释器跟别人不一样”这种小事。定基线这件事花不了多少时间但能省掉无数次今天这种排查。我自己的做法是在所有涉及repo的机器上把repo_diag和一份环境说明放在同一个位置谁遇到问题先跑一遍自查跑完再看文档。这套习惯养成之后团队里因为环境不一致而卡住的次数明显少了。至于formatter这个报错我现在看到它的第一反应已经不是去搜怎么修而是直接换启动器——因为修过太多次了每修一次都在心里骂一句这个模块为什么不早点被清掉。