TypeError 类型不匹配速查：str 拼接 int 与 None 参与运算

更新时间：2026-10-24。FAQ 速查页，面向被 TypeError 拦住的同学。TypeError 是 Python 报错里出现频率最高的一类，也是信息最足的一类：报错原文会把「你想干什么操作、两边各是什么类型」写得明明白白——can only concatenate str (not "int") to str 直接告诉你 str 拼了 int，unsupported operand type(s) for +: 'NoneType' and 'int' 直接告诉你 None 参加了加法。所以 TypeError 的排查核心不是「找」而是「读」：读懂报错原文，再顺着操作数回溯「这个值的类型为什么不是我以为的那个」。真因集中在六根轴：str 与 int 直接拼接、函数没 return 返回了 None 参与运算、bytes 与 str 在网络/文件 IO 边界混淆、函数参数个数传错、对 None 或不可迭代对象做解包、以及运算两边类型组合本身就不支持。

本文要回答的问题

• can only concatenate str (not "int") to str 到底哪里错了？
• 变量怎么会变成 NoneType？
• a bytes-like object is required, not 'str' 在哪一层转？
• 函数明明定义了三个参数，为什么说我传了四个？
• cannot unpack non-iterable NoneType object 怎么查？

一、报错原文与典型现象

TypeError 的真身（工程路径以 /proj/demo 占位）：

$ python3 /proj/demo/bill.py
Traceback (most recent call last):
  File "/proj/demo/bill.py", line 4, in <module>
    msg = "金额: " + amount
TypeError: can only concatenate str (not "int") to str
# str 拼了 int——Python 不做隐式类型转换

$ python3 /proj/demo/calc.py
Traceback (most recent call last):
  File "/proj/demo/calc.py", line 6, in <module>
    total = price + 1
TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'
# price 是 None：上游函数忘了 return，None 顺着变量流进了加法

$ python3 /proj/demo/net.py
Traceback (most recent call last):
  File "/proj/demo/net.py", line 8, in <module>
    sock.send("GET / HTTP/1.0\r\n\r\n")
TypeError: a bytes-like object is required, not 'str'
# socket 要 bytes，给的是 str——IO 边界的编码转换漏了

先读懂 TypeError 的报告结构：最后一行的格式是「操作描述 + 涉及的实际类型」。unsupported operand type(s) for +: 'A' and 'B' 告诉你加法两边实际是 A 和 B；can only concatenate str (not "X") to str 告诉你拼接时混进了 X。类型名就是线索本身——看到 NoneType 就往上游查 return，看到 bytes 就查 IO 边界。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
can only concatenate str (not "int")	str 直接拼数字	看报错行拼接的变量	f-string 或 str() 显式转换
unsupported operand: NoneType + X	上游函数忘 return，变量是 None	print(type(变量)) 确认	修上游 return / 调用处判空
a bytes-like object is required	socket/二进制 IO 给了 str	看是网络还是文件边界	.encode() / .decode() 过边界
takes 3 arguments but 4 were given	调用多传了参数（常因 self 算错）	对比定义与调用	对齐参数个数与顺序
cannot unpack non-iterable NoneType	函数返回 None 被解包	看解包右侧的来源	修返回值 / 判空后再解包
not supported between instances of A and B	排序/比较的两边类型不可比	看比较符两边类型	统一类型或自定义 key

三、排查决策图

这张图是 TypeError 的标准动线，颜色按角色区分：红是报错入口与定罪的根因，蓝是排查动作，绿是验证通过，橙是修复动作，紫是防复发沉淀。

读这张图抓住「按类型名分流」这条主线：报错原文里的类型名是分诊依据——NoneType 一律往上游查 return，bytes/str 对查 IO 边界，arguments 类直接对签名。九条流最终汇到同一个根：Python 是强类型语言，不做隐式转换，一切转换都要你显式写出来。

四、逐条排查展开

第一病因：str 与 int 直接拼接。 Python 是强类型语言——不像 JavaScript 会把 "" + 1 悄悄变成 "1"，"金额: " + 100 直接报错。处置首选 f-string，转换和格式化一步完成：

amount = 100
msg = f"金额: {amount}"        # 推荐：f-string 自动转
msg = "金额: " + str(amount)   # 也可以：显式 str()

同类高频变体：print("第" + i + "行")（循环里 i 是 int）、日志拼接里混数字、URL 拼接里混端口。统一口径：字符串组装一律 f-string，不用 + 拼，这类错误就从根上消失。

第二病因：None 参与运算——上游忘了 return。 NoneType 出现在运算里，真凶几乎从不在报错行，而在上游某个函数：分支漏了 return、return 写在了 if 里但条件没命中、或者干脆只 print 没 return。Python 函数没有显式 return 时默认返回 None，这个 None 顺着变量一路流进加法才爆炸。排查动线：

def get_price(item):
    if item in catalog:
        return catalog[item]
    # 没命中时什么都没返回——调用方拿到 None

price = get_price(x)
print(type(price))   # <class 'NoneType'>——实锤

处置两条腿：上游补全所有分支的 return（查不到时该 return 0、抛异常还是返回 None，要在接口语义里定死）；调用处对「可能为 None 的返回值」判空再用。if price is not None: 是防御，assert price is not None 是显式契约，任选其一都比裸用强。

第三病因：bytes 与 str 在 IO 边界混淆。 Python 3 把文本（str）与二进制（bytes）彻底分开：socket、管道、二进制模式文件（open(path, "rb")）进出的都是 bytes，而你的业务逻辑用的是 str，边界上必须显式转码。口诀：

data.encode("utf-8")    # str -> bytes：发送/写入前
raw.decode("utf-8")     # bytes -> str：接收/读出后

四个方向记牢：网络发送前 encode、接收后 decode；"rb" 读出的 decode 成文本再处理、写文本文件用文本模式 "w" 别用 "wb"。报错 a bytes-like object is required 是缺 encode，can't concat str to bytes 是方向搞反。JSON 场景注意 json.loads 收 str（3.6+ 也收 bytes），但老式代码常先 decode 一道。

第四病因：函数参数个数不符。 takes 3 positional arguments but 4 were given——先别急着数，注意 Python 报的数字把 self 算在内：方法定义 def move(self, x, y) 是「3 个参数」，普通调用传 2 个就够。多传常见三种：把方法当函数直接调（Class.move(obj, x, y) 时忘了第一个就是 self）、重构加了参数但旧调用点没改、*args 收集后展开多了一层。反向错误 missing 1 required positional argument 同理。处置：定义与调用并排看，逐位对齐；关键字参数（f(x=1, y=2)）能根除顺序错位类问题，多参数函数建议强制关键字传参。

第五病因：None 或不可迭代对象被解包。 a, b = get_pair() 在 get_pair 返回 None 时报 cannot unpack non-iterable NoneType object；返回单个值报 not enough values to unpack。这是第二病因的解包版：根因还是上游返回值不符合约定。处置同构：上游保证返回结构稳定（异常分支也返回 (None, None) 或直接抛异常），调用处先判再拆。字典遍历解包 for k, v in d.items() 忘了 .items() 时报的是另一类（cannot unpack non-iterable 且类型名是键的类型），补上 .items() 即可。

第六病因：运算组合本身不支持。 '3' < 5 报 '<' not supported between instances of 'str' and 'int'——排序混合类型列表（sorted([1, "a", 2])）是这条的重灾区，Python 3 不再像 Python 2 那样给不同类型定一个人工顺序。处置：排序前统一类型（sorted(map(str, data))），或给 key 函数显式指定排序依据：sorted(data, key=lambda x: (isinstance(x, str), x)) 把数字和字符串分组排。同类：None > 0、列表减列表、{} + {}（3.9 前 dict 不支持 +，用 | 或 {**a, **b}）。

类型断言调试法。 TypeError 排查的通用一手：在报错行之前打印真实类型。

print(type(price), repr(price))   # type 给类名，repr 给带类型的值——None 和 "None" 一眼区分

repr 比 print 可靠：字符串 "None" 和 None 用 print 打出来一模一样，repr 会带引号区分。复杂场景上 assert isinstance(x, int), f"expect int, got {type(x)}"，让类型假设在出错现场显形。

五、规范做法与预防

• 字符串组装一律 f-string：消灭 str+int 整类错误，还顺带统一格式。
• 函数每个分支都 return：查不到是返回默认值还是抛异常，接口文档里定死，不许「漏着漏着返回 None」。
• IO 边界显式转码：网络/文件边界 encode/decode 成对出现，CR 见裸 socket send str 直接打回。
• 多参数函数强制关键字传参：def f(*, x, y) 让调用方必须写名字，顺序错位类错误归零。
• 类型注解 + mypy 进 CI：def get_price(item: str) -> float | None 把 None 泄漏、类型错位在运行前拦下。
• 解包前判结构：对「可能不稳定的返回值」先判再拆，或改用 .get() 式访问。

这一篇在知识体系里的位置

本篇是 Python 排错速查簇的类型运行期篇，定位「值对了但类型不对」：语法层面就写错了看 SyntaxError 与 IndentationError 速查；编码层面的 str/bytes 解析失败看 UnicodeDecodeError 编码报错速查；资源耗尽类看 MemoryError 与 RecursionError 速查；解释器直接崩溃看 Python 段错误崩溃速查；模块找不到看 ModuleNotFoundError 速查。「读报错原文的类型名分诊」这条心法对一切强类型语言通用。

一句话总结

TypeError 的排查核心是把报错原文当分诊单读：can only concatenate str 就用 f-string 或 str() 显式转换；NoneType 出现在运算里就往上游查谁忘了 return（函数无显式 return 默认返回 None）；bytes-like object is required 在网络/文件边界补上成对的 encode/decode；参数个数不符注意 self 也算一个、定义调用并排对齐；解包失败先判上游返回结构再拆；排序比较前统一类型或给 key 函数。防复发主线一条：类型注解加 mypy 进 CI，让类型错位在运行之前被拦下——Python 不做隐式转换，一切转换都要显式写出来。