在 Flask 的 Jinja2 模板里遍历字典，是渲染动态内容时绕不开的操作。很多刚接触的开发者会直接拿 Python 的 for key in dict 写法套用到模板里，结果发现只拿到了键，想要值还得再写一次 dict[key]。实际上模板语法和 Python 类似，但对字典的处理有一些自己的约定和限制。下面我从实际排查中遇到的情况出发，把几种遍历方式、适用场景以及容易踩的坑拆开来说。

基本遍历方式：先搞清楚要拿键还是值

在 Flask 的 Jinja2 模板中，对字典进行遍历最直接的方式就是使用 for 循环。默认情况下，{% for key in dict %} 会依次取出字典的键。如果你需要同时获取键和对应的值，可以采用 {% for key, value in dict.items() %}。注意，这里调用的是 Python 字典的 items() 方法，它返回一个包含键值对的可迭代对象，模板引擎会自动解包为两个变量。

这个方式是最常用的，但有个细节容易被忽略：在模板里写 dict.items() 时，后面不能加括号以外的参数。如果视图函数传进来的字典是 OrderedDict 或其他自定义字典子类，只要它实现了 items()，模板都能正常遍历。一个简单验证办法是直接在模板里写 {{ dict.items() | list }}，看看渲染出来的列表结构是否符合预期。如果遇到 UndefinedError，优先检查字典变量名是否传递正确，或者模板上下文里有没有被覆盖。

当你需要同时操作字典的键和值时，推荐使用 dict.items()。例如，{% for key, value in my_dict.items() %} 可以在循环体中通过 {{ key }} 和 {{ value }} 分别访问。如果你只想遍历值，可以使用 dict.values()；只想遍历键，则直接使用 dict 或 dict.keys()。但请注意，在模板中调用 keys() 或 values() 会返回视图对象，直接遍历即可，无需额外转换。

这里补充一个判断点：如果模板里只需要用键，就不要调用 dict.keys()，直接 {% for key in dict %} 即可，少一次方法调用，也避免视图对象在老旧 Jinja2 版本中的兼容问题。虽然视图对象可以直接迭代，但部分老版本环境（比如 Jinja2 2.10 以下）可能对视图对象的 __iter__ 支持不完整，直接遍历原字典是最稳妥的。

排序与条件过滤：按需取出子集

如果希望按照特定顺序遍历字典，可以在 for 循环中加入 sort 过滤器。例如，{% for key in dict | sort %} 会按字母顺序遍历键。更复杂的场景下，可以先对 items 排序：{% for key, value in dict.items() | sort(attribute='0') %} 这表示按键排序。注意排序会返回排序后的列表，不会影响原字典。

在用 sort(attribute='0') 时，'0' 指的是 items 返回的元组的第一个元素（即键）。如果想按值排序，就把 attribute 改成 '1'。但这里有个容易出错的地方：如果字典的值类型不统一（比如既有整数又有字符串），排序会抛出 TypeError，因为 Python 无法对不同类型的对象进行排序。解决办法是确保所有值类型可比较，或者在视图函数中先转换为统一类型。另外，sort 过滤器默认升序，要降序可以加 reverse=True：{% for key, value in dict.items() | sort(attribute='1', reverse=True) %}。

在遍历过程中，常需要根据条件过滤某些键值对。你可以在循环内部使用 if 语句，例如：{% for key, value in dict.items() if value > 10 %} 这样只会遍历值大于10的条目。也可以在循环体外部先过滤，但注意模板中不支持在 for 标签的 if 子句中使用复杂的表达式，仅支持简单比较。如果需要复杂逻辑，建议在视图函数中预处理。

这里我推荐一个做法：如果过滤条件涉及多个字段或者需要函数判断，就在视图函数里用列表推导式或 filter() 处理完再传到模板。比如 filtered_dict = {k:v for k,v in original.items() if condition}。这样模板里的 for 循环只负责渲染，逻辑清晰，排查时也只需要查一个地方。

处理顺序依赖和避免修改字典

在 Jinja2 模板中遍历字典时，一个常见的陷阱是依赖遍历顺序。虽然 Python 3.7+ 的字典保持插入顺序，但早期版本或某些框架配置下顺序可能不固定。如果你的业务逻辑依赖顺序（例如渲染配置项的顺序），建议在视图函数中将字典转换为有序的列表或使用 OrderedDict。在模板中直接遍历时，不要假设任何顺序，除非你明确使用了 sort 过滤器。

这里有一个实际的排查案例：一位同事在 Flask 应用里用 session 对象保存用户偏好，模板里按 {% for key in session %} 遍历，结果在 Python 3.6 环境下测试时每次刷新的顺序都不同。排查后发现 session 使用的是 Werkzeug 的 SessionDict，其底层是普通的 dict，顺序在 Python 3.6 中不可靠（尽管插入了特定键，但某些操作可能改变顺序）。解决办法是把需要的键值对提取到一个 OrderedDict 中再传给模板。如果你需要确认当前环境是否有顺序保证，可以在视图函数里临时输出 dict.keys() 的顺序，或者用 sys.version_info 判断 Python 版本。

一个容易忽略的风险是在 for 循环内部尝试修改正在遍历的字典。例如，{% for key in dict %} ... {% if condition %}{% do dict.pop(key) %}{% endif %} 这种写法会导致遍历行为异常或运行时错误。Jinja2 本身不支持在模板中修改字典（除非使用自定义扩展），即使支持，也强烈不建议这样做。正确的做法是在视图函数中完成所有修改，模板只负责展示。

如果你确实需要在模板中动态排除某些键，可以在视图函数里提前构建一个排除后的字典。比如 excluded_keys = ['admin', 'secret']; display_dict = {k:v for k,v in full_dict.items() if k not in excluded_keys}。这样模板里直接遍历 display_dict，既安全又容易维护。另外，如果只是隐藏某些值而不删除键，可以在模板里用 {% if key != 'secret' %} 条件渲染，也不影响遍历本身。

实用调试与回滚边界

当模板里的字典遍历结果不符合预期时，先检查视图函数传入的字典内容。可以在模板里临时加一句 {{ dict | pprint }} 或 {{ dict }}，看渲染输出是不是你想要的。如果字典很大，可以用 {{ dict.keys() | list }} 先看有哪些键。下一步确认遍历时变量名有没有拼写错误：比如 {% for key in my_dict %}，但模板上下文里变量名是 mydict，就会报 UndefinedError。一个常见的回滚操作是：先在视图函数里把字典转成 JSON 字符串 import json; json.dumps(dict)，然后在模板里用 {{ jsondata }} 输出，检查结构是否完整。

另外，如果使用了 sort 过滤器却得到非预期的顺序，可以在排序前先用 {{ dict.items() | list }} 查看原始顺序，再用 {{ dict.items() | sort(attribute='0') | list }} 查看排序后结果。这样能快速定位是排序参数写错了，还是原始数据本身就不符合预期。需要记得，修改模板后要清除浏览器缓存或重启 Flask 开发服务器（如果开启了模板缓存），否则可能看不到改动效果。在 Flask 配置中设置 TEMPLATES_AUTO_RELOAD = True 可以避免手动重启。

对于依赖顺序的业务，如果因为历史原因无法改用 OrderedDict，可以考虑在视图函数里先按特定键排序生成列表，再把列表传到模板。比如 sorted_items = sorted(dict.items(), key=lambda x: x[1])，模板里直接 {% for key, value in sorted_items %}。这样虽然多了一次排序，但能确保顺序稳定。不过要注意，在 Python 3.7+ 中普通字典已经有序，如果部署环境统一，可以直接用 dict 而无需额外操作。建议在开发环境的 requirements.txt 中注明 Python 版本要求，避免跨版本部署时出现顺序问题。