SyntaxError: invalid syntax 表明代码未在 Python 3.9+ 下运行，因 | 合并字典运算符仅支持于 3.9 及以上版本；需验证 sys.version、解释器路径及环境配置，并确保操作数均为 dict 类型。
直接报 SyntaxError: invalid syntax，说明你根本没在 Python 3.9+ 下运行；报 TypeError: unsupported operand type(s) for |，大概率是操作数里混进了 None、list 或其他非 dict 类型。
检查 Python 版本是否真为 3.9+
别只看终端里写的 python --version，有些环境（比如 conda、pyenv、IDE 内置解释器）会默认调用旧版本。最稳妥的方式是在代码里加一行验证：
import sys print(sys.version)
输出必须是 3.9.x 或更高（如 3.10.12）。如果显示 3.8.10 或更低，| 运算符在语法解析阶段就会被拒绝——这不是逻辑错误，而是解释器根本不认识这个符号。
- 用
which python（macOS/Linux）或where python（Windows）确认实际执行路径 - VS Code 或 PyCharm 中右下角 Python 解释器版本可能和终端不一致，需手动切换
- CI/CD 脚本里写
python:3.9不等于保证用的是 3.9+，Docker 镜像或 GitHub Actions 的setup-python动作必须显式指定3.9或更高
确认左右操作数都是 dict 类型
| 只接受两个 dict，不自动转换、不兜底、不降级。常见翻车点：
立即学习“Python免费学习笔记（深入）”；
-
user_config = json.loads(request.body) | default_config——json.loads()失败时返回None，None | dict直接炸 -
data = api.get_user() | fallback—— API 返回空数组[]或字符串"{}"，都不是dict -
config = base | os.getenv("EXTRA_CONFIG")—— 环境变量是字符串，不是字典
正确做法是显式校验：
if isinstance(extra, dict):
config = base | extra
else:
config = base.copy() # 或 raise ValueError("extra must be a dict")别用 base | (extra or {})：当 extra 是 0、False、"" 时也会被转成空字典，掩盖真实问题。
合并嵌套字典时为什么键值被整个替换？
| 和 update() 都只做浅合并。例如：
{"a": {"x": 1}} | {"a": {"y": 2}}结果是 {"a": {"y": 2}}，不是 {"a": {"x": 1, "y": 2}}。这是因为内层 {"x": 1} 被整个当作值，被右侧的 {"y": 2} 覆盖了。
- 若需深合并，得自己递归处理，或用第三方库如
deepmerge - 用字典推导式或
copy.deepcopy()+ 循环更新也能实现，但注意循环引用风险 - 别指望
typing.cast(dict, x)能绕过运行时类型检查——它只骗过 mypy，不改变实际行为
真正容易被忽略的点是：错误往往不出现在 | 这一行，而出现在上游数据来源没做清洗。合并前多一次 isinstance(x, dict) 检查，比事后 debug 十分钟强得多。
