字符串格式化这件事，说简单也简单，"{}".format(x)谁都会写；说复杂也复杂，真到要拼一张对齐的报表、补一串定长的编号、把浮点数压到两位小数还带千分位的时候，很多人就开始翻文档、试错、再翻文档。format这套东西属于典型的"入门十分钟，精通靠踩坑"——语法糖背后藏着一整套格式迷你语言（format spec），填充、对齐、符号、进制、精度、类型符各有各的规矩，组合起来还有优先级和互斥关系。这篇就把str.format()这条线从头到尾捋一遍，重点放在填充与对齐、数字格式化这两块最容易出问题的地方，顺带把常见坑和实操心得摊开讲。不管你是刚学 Python 的新手，还是写了几年但每次格式化都要查一下的老手，下面这些内容应该都能直接拿去用。

1. 先把 format 的语法骨架立起来

很多人用format是"照着例子改"，改对了就用，改错了就懵。根子在于没把格式说明符的完整结构记住。其实它有一套固定的语法顺序，记住这个顺序，绝大多数报错都能自己推出来。

1.1 格式说明符的完整结构：一个都不能乱序

str.format()里花括号内的内容，完整形式是这样的：

{字段名:格式说明符}

冒号后面那一段就是格式迷你语言，它的标准结构按顺序是：

[[填充字符]对齐方式][符号][#][0][宽度][,][.精度][类型]

注意，这是严格顺序，不能乱。比如你不能把宽度写在符号前面，也不能把精度写在类型后面。我见过有人写{:2.2f}以为能控制宽度和精度，结果宽度确实生效了，但一旦整数部分超过 2 位就"撑破"了——因为宽度是最小宽度，不是截断宽度，这个后面细说。

拆开看每一段的作用：

这张表建议直接记住。实际写的时候，大部分场景只会用到其中三四段，但知道全貌之后，遇到"为什么我这个格式符不生效"就能快速定位——多半是顺序错了，或者某两段互斥。

1.2 字段名不只是数字：位置、关键字与属性访问

冒号前面那部分（字段名）也有讲究，很多人只会用{}自动编号和{0}手动编号，其实它支持的东西更多：

• 自动编号："{} {}".format(a, b)，按出现顺序填。
• 手动编号："{1} {0}".format(a, b)，可以重复引用、可以乱序。
• 关键字："{name}".format(name="x")，可读性最好。
• 属性访问："{0.real}".format(3+4j)，直接取对象属性。
• 下标访问："{0[1]}".format(["a","b"])，取列表元素。

这里有个硬性规则：自动编号和手动编号不能混用。你写"{} {1}".format(a, b)会直接抛ValueError。原因很简单——自动编号靠内部计数器，手动编号打乱了计数逻辑，Python 干脆禁止混用。我早期就踩过这个坑，一个模板里前面图省事写{}，后面又想引用同一个参数写{0}，结果运行直接崩。

提示：字段名里如果要出现字面量的花括号，用双写转义，{{输出{，}}输出}。这在拼 JSON 模板或者写正则的时候特别常见。

1.3 为什么 format 比 % 更值得用

老代码里到处是"%s %d" % (a, b)，能用，但问题不少。%格式化对参数类型敏感，%d传个浮点会截断、传个字符串直接报错；参数顺序靠位置，参数一多就容易对错位；而且它不支持命名引用之外的高级特性。format的优势在于：类型更宽容（{}什么都能接）、支持命名和属性访问、格式说明符表达能力更强、还能配合format_map处理字典。

当然，Python 3.6 之后有了 f-string，日常拼接更推荐 f-string——它本质上是format的语法糖，格式说明符完全通用。但str.format()并没有过时：需要模板复用（比如从配置文件读模板、批量填充）的时候，format比 f-string 更合适，因为模板是字符串对象，可以存起来反复用。所以把format的格式语言吃透，等于同时掌握了 f-string 的格式化能力，一举两得。

2. 填充与对齐：让输出"排好队"的底层逻辑

填充和对齐是format里最实用、也最容易出细节问题的部分。做命令行报表、日志对齐、生成定长文本文件，全靠这一块。但很多人只知道{:>10}右对齐，遇到中文、遇到零填充、遇到自定义填充字符就开始试错。

2.1 对齐三兄弟与默认行为的陷阱

对齐符号就三个：

• <左对齐（内容靠左，右边补填充）
• >右对齐（内容靠右，左边补填充）
• ^居中对齐（两边均分填充）

看起来简单，但默认对齐方式取决于类型，这是第一个坑。规则是：

• 字符串默认左对齐（<）
• 数字默认右对齐（>）

也就是说"{:10}".format("abc")得到"abc "（左对齐补空格），而"{:10}".format(123)得到" 123"（右对齐补空格）。这个差异是符合直觉的——文本左对齐、数字右对齐是排版常识——但如果你不显式写对齐符，混排字符串和数字时就会对不齐。

第二个坑是填充字符必须和对齐符一起出现。你写"{:*10}".format("abc")会报错，因为*被当成了填充字符，但后面没跟对齐符，解析器不知道你要怎么对齐。正确写法是"{:*<10}"（左对齐，星号填充）或"{:*>10}"（右对齐）。记住：填充字符永远紧跟在对齐符前面，单独出现无效。

第三个坑是填充字符只能是一个字符。"{:ab>10}"会报错，因为a被当填充字符后，b不是合法对齐符。想要多字符填充，只能自己用字符串方法拼，format本身不支持。

2.2 零填充的两种写法与它们的差异

数字补零是高频需求，比如生成000123这种定长编号。有两种写法：

"{:06d}".format(123) # '000123' "{:0>6d}".format(123) # '000123'

第一种06d里的0是"零填充标志"，它等价于"填充字符为 0 + 右对齐"，是专门给数字设计的简写。第二种0>6d是显式写"填充 0、右对齐、宽度 6"。两者结果一样，但有个关键区别：

0标志只对数字类型有效，且会正确处理符号位。比如"{:08.2f}".format(-3.14)得到"-0003.14"，负号在最前面，零补在数字部分——这是符合财务/编号习惯的。而如果你用"{:0>8}".format("-3.14")对字符串操作，得到的是"000-3.14"，零跑到负号前面去了，完全错误。

所以结论很明确：给数字补零用0标志（如08d、08.2f），不要用0>去糊字符串。后者只适合纯数字字符串且没有符号的情况，一旦有负号或需要类型转换就会翻车。

2.3 中文对齐：宽度算的是字符数不是显示宽度

这是做中文报表时最头疼的问题。format的宽度计算的是字符个数，不是显示宽度。一个中文字符在等宽字体下通常占两个英文字符的宽度，但format只算 1。结果就是：

"{:<10}".format("姓名") # '姓名 '，看起来只补了8个空格 "{:<10}".format("name") # 'name '

上面两行在终端里显示时，"姓名"那行实际占的视觉宽度是 4+8=12，而"name"那行是 4+6=10，两者根本对不齐。

解决办法有两个方向。一是手动按显示宽度补齐：先算出字符串的显示宽度（中文算 2，英文算 1），再决定补多少空格。可以用unicodedata.east_asian_width判断字符宽度：

import unicodedata def display_width(s): return sum(2 if unicodedata.east_asian_width(c) in 'WF' else 1 for c in s) def pad_display(s, width, align='<'): gap = width - display_width(s) if gap <= 0: return s if align == '<': return s + ' ' * gap if align == '>': return ' ' * gap + s left = gap // 2 return ' ' * left + s + ' ' * (gap - left)

二是干脆放弃 format 的对齐，改用表格库（如tabulate之类），它们内部处理了东亚字符宽度。但如果只是简单场景，上面这个pad_display函数足够用，而且没有额外依赖。

注意：east_asian_width返回W（宽）和F（全角）的字符按 2 算，Na（窄）、H（半角）、N（中性）按 1 算。这个判断对绝大多数中文、日文、韩文场景是准确的，但个别符号（如某些 emoji）可能不准，做严格对齐时要实测。

2.4 居中填充的"偏左"细节

^居中对齐在填充字符数为奇数时，会多补在右边。比如"{:^6}".format("ab")，总宽 6，内容 2，需要补 4 个，左右各 2，结果" ab "。但如果总宽 7，需要补 5 个，左边补 2、右边补 3，得到" ab "——多出来的那个在右边。

这个细节在做标题装饰（比如==== 标题 ====）时要注意，如果你希望多出的填充在左边，就得自己算，不能依赖^。我一般做装饰标题时直接手写：

title = "报表" total = 20 left = (total - len(title)) // 2 right = total - len(title) - left line = "=" * left + title + "=" * right

这样左右填充可控，也避免了中文宽度问题（因为这里按字符数算，装饰符是 ASCII，视觉上一致）。

3. 数字格式化：精度、进制与千分位的组合拳

数字格式化是format的另一大块，也是参数最多、组合最灵活的部分。浮点精度、科学计数、百分比、进制转换、千分位，每一项单独用都不难，难在组合时的顺序和互斥关系。

3.1 浮点精度：.2f到底做了什么

"{:.2f}".format(3.14159)得到"3.14"，这是四舍五入吗？严格说，Python 的浮点格式化遵循的是银行家舍入（round half to even），不是传统的四舍五入。看这个例子：

"{:.0f}".format(2.5) # '2' "{:.0f}".format(3.5) # '4' "{:.1f}".format(0.25) # '0.2' "{:.1f}".format(0.35) # '0.3'（注意，不是 0.4）

2.5舍到2、3.5舍到4，因为 2 是偶数、4 是偶数——遇到"正好一半"时向偶数靠拢。0.35那个更微妙，因为0.35在二进制浮点里其实略小于 0.35，所以舍到0.3。这不是 bug，是浮点表示和舍入规则共同作用的结果。

如果你的业务要求"传统四舍五入"（比如财务场景），不能直接用format，得用decimal模块配合ROUND_HALF_UP：

from decimal import Decimal, ROUND_HALF_UP def round_half_up(value, digits): q = Decimal(1).scaleb(-digits) return Decimal(str(value)).quantize(q, rounding=ROUND_HALF_UP) print(round_half_up(0.35, 1)) # 0.4 print(round_half_up(2.5, 0)) # 3

注意这里用str(value)而不是直接传 float，是为了避免浮点误差在Decimal构造时被带进去。这个细节在金额计算里非常关键，我见过因为直接Decimal(0.35)导致结果偏差的案例。

3.2 精度与宽度的关系：宽度是下限不是上限

前面提过一嘴，这里展开说。"{:8.2f}".format(1234.5678)得到" 1234.57"——宽度 8 是最小宽度，内容1234.57已经 7 个字符，加上前导空格正好 8。但如果数字更大，比如123456.789，格式化后是"123456.79"，9 个字符，宽度 8 被突破，不会截断。

这个行为经常让人误解。有人以为{:8.2f}能保证输出正好 8 位，实际上它只保证"至少 8 位，不够补空格，超了不管"。如果你需要严格定长（比如生成固定宽度的数据文件），必须自己判断并截断或报错：

def fixed_width_num(value, width, precision): s = f"{value:.{precision}f}" if len(s) > width: raise ValueError(f"数值 {s} 超出宽度 {width}") return s.rjust(width)

这个"宽度是下限"的规则对字符串同样适用："{:5}".format("abcdefg")原样输出"abcdefg"，不会截断。想要截断得用切片，format不管这事。

3.3 千分位、百分比与科学计数法的类型符选择

数字类型符有一张表，常用的几个：

几个容易踩的点：

f不写精度默认 6 位小数。"{:f}".format(3.14)是"3.140000"，不是"3.14"。想要原样，要么写"{:g}"（自动选择），要么显式给精度。

%会自动乘 100。"{:%}".format(0.5)是"50.000000%"，别自己先乘 100 再格式化，会变成 5000%。

千分位,和进制类型符互斥。"{:,x}".format(123456)会报错，因为千分位只对十进制有意义。同理,也不能和b、o组合。

#前缀开关："{:#x}".format(255)得到"0xff"，"{:#b}".format(5)得到"0b101"。做调试输出或者生成代码时有用，但注意#和0填充同时用时，前缀会算进宽度里。

3.4 符号控制：正数也要带加号的场景

默认情况下正数不显示+，负数显示-。但有些场景（比如显示涨跌幅、温度变化）需要正数也带+。用符号段：

• +：正负都显示符号，"{:+d}".format(5)→"+5"
• -：默认行为，只有负数显示
• 空格：正数前补一个空格，负数正常，"{: d}".format(5)→" 5"，这样正负数宽度一致，对齐好看

空格符号这个技巧在对齐正负数时特别有用。比如一列数字有正有负，用{: d}能让它们宽度一致，不会因为负号多一位而错位。这个细节很多教程不讲，但实际做报表时很实用。

4. 实战里那些文档不会写的坑

前面讲的是"应该怎么用"，这一节讲"实际用起来会怎么翻车"。这些坑大多不是语法错误，而是语义误解——代码能跑，结果不对，排查起来更费劲。

4.1 花括号转义与模板拼接的连环坑

拼 JSON 或者写带{}的模板字符串时，花括号转义是必踩的坑。规则是{{输出{、}}输出}。但如果你要拼的模板里本来就有大量花括号（比如一个 JSON 片段），手动双写会非常痛苦，而且容易漏。

更隐蔽的坑是转义和字段混用。比如你想输出{name}这个字面量，同时又要格式化别的字段：

# 错误：{name} 会被当成字段 "{name} is {age}".format(age=20) # KeyError: 'name' # 正确：字面量花括号要双写 "{{name}} is {age}".format(age=20) # '{name} is 20'

还有一种情况是模板来自外部（配置文件、数据库），里面可能包含用户输入的花括号，直接format会抛KeyError或IndexError。稳妥做法是用string.Template（用$占位）或者自己做占位符替换，避免format解析外部内容。如果非要用format，至少用format_map配合defaultdict兜底：

from collections import defaultdict safe = defaultdict(lambda: "", {"age": 20}) "{name} is {age}".format_map(safe) # ' is 20'

这样缺失的字段变成空字符串而不是报错，适合处理不完全可控的模板。

4.2 类型不匹配的静默失败

format比%宽容，但宽容有时是坏事。"{:d}".format(3.9)会抛ValueError（浮点不能直接当整数格式化），这个还算明显。但"{:s}".format(123)呢？会得到"123"——s类型符对任何对象都调用str()，不报错。这意味着如果你本意是格式化数字却误写了s，精度、千分位全部失效，而且不报错。

更隐蔽的是自定义对象的__format__。如果你传的对象实现了__format__，format会调用它，行为完全由对象决定。调试时如果发现格式化结果诡异，先确认对象的__format__有没有被重写。

还有一个经典问题："{:d}".format(True)得到"1"，因为bool是int的子类。这个在布尔值当数字用时容易出意外，虽然不算 bug，但读代码时容易看漏。

4.3 性能：批量格式化时 format 不是最快的

单次格式化，format和 f-string 差距可以忽略。但如果是百万次循环里的格式化，差距就出来了。f-string 在编译期就解析了格式，运行时开销最小；str.format()每次都要解析模板字符串；%介于两者之间。

我做过一个粗略测试（具体数字因机器而异，看趋势即可）：对同一个模板做 100 万次格式化，f-string 大约比str.format()快 1.5 到 2 倍。所以如果是热点路径上的格式化，优先 f-string；如果模板需要复用（比如从配置读一次、循环里用很多次），可以先把模板format成"半成品"再拼，或者用string.Template的substitute。

不过要强调：绝大多数业务代码里格式化不是瓶颈，别为了这点性能把代码写得难读。只有在 profiling 确认格式化占了大头时才需要优化。

4.4 本地化与千分位符号的差异

,千分位用的是逗号，但不同地区的习惯不同（有的用空格、有的用点）。format本身不支持自定义千分位符号。如果要做本地化输出，得用locale模块或者手动替换：

import locale locale.setlocale(locale.LC_ALL, '') # 按系统设置 "{:n}".format(1234567) # 用 n 类型符，走 locale 的千分位

n类型符是format里比较冷门的一个，它按当前 locale 格式化数字。但locale.setlocale是全局状态，多线程环境下要小心，而且不同系统上行为可能不一致。做国际化产品时，更稳的做法是用专门的格式化库，或者自己维护一套符号映射。

5. 把 format 用顺手的几个习惯

写到这里，语法和坑基本覆盖了。最后分享几个我长期用下来觉得值得固化的习惯，都是些小动作，但能省不少调试时间。

第一，模板和参数分离。需要复用的模板，单独定义成常量，用命名占位符（{name}而不是{}），这样模板改了不影响调用方，调用方传参也不依赖顺序。命名占位符的可读性远高于位置占位符，尤其在参数多的时候。

第二，数字格式化统一封装。项目里如果到处散落"{:.2f}"，一旦精度要求变了（比如从 2 位改 3 位），要改几十处。封装成fmt_money(x)、fmt_percent(x)这类函数，精度和舍入规则集中管理，改一处生效全局。前面提到的银行家舍入问题，也在这个封装层统一处理掉。

第三，对齐需求先想清楚是"字符对齐"还是"显示对齐"。纯英文数字场景，format的对齐够用；一旦涉及中文，直接上显示宽度计算或者表格库，别在format上硬拗，拗不出来的。

第四，调试格式化结果时，用repr()看真实内容。空格填充在终端里看不出来，print(repr("{:>10}".format("ab")))能清楚看到' ab'，比肉眼数空格靠谱得多。这个习惯帮我定位过好几次"看起来对齐了其实没对齐"的问题。

第五，别怕用 f-string。很多人因为先学了format就一直用format，其实日常拼接 f-string 更简洁，格式说明符完全一样。把format的格式语言学透，f-string 直接受益，两者不是替代关系，是同一套知识的不同入口。需要模板复用时用format，需要就地拼接时用 f-string，各取所长。

格式化这东西，说到底就是把"数据"翻译成"给人看的文本"，翻译得准不准、齐不齐、符不符合业务习惯，全在这些细节里。语法十分钟能背完，但真正用顺，靠的是每次遇到对不齐、舍不对、补不对的时候，知道该往哪个方向查。上面这些坑我基本都踩过一遍，希望你看完能少踩几个。