开头接触 Python 久了你会发现格式化字符串是绕不开的基本功而其中最古老、也最容易被新手忽略的就是%系列占位符。要说清楚 Python 变量格式占位符%系列我先把结论放在前面这玩意儿是从 C 语言 printf 继承过来的老牌语法哪怕现在 f-string 大行其道你在日志模块 logging、字符串格式化、甚至一些老项目的源码里还是会频繁撞见它。这篇文章适合刚入门想搞懂格式化原理的 Python 新手也适合写了一阵子代码但见到%s、%d、%(name)s就发懵的进阶学习者。我会从最基础的占位符类型讲到格式控制符再到和 format()、f-string 的横向对比最后附上我实际踩过的坑和排查技巧保证你看完能直接上手用。很多人一看到%就条件反射想到取模运算其实在字符串场景里它完全是另一回事。它做的事情很简单把字符串里的占位符替换成你要塞进去的变量。但恰恰是这种“简单”衍生出了不少微妙细节比如占位符数量不对时会抛 TypeError浮点精度控制不好会四舍五入出错映射键用错了直接 KeyError。这些坑我在后文都会逐一拆解先别急我们从最基础的部分开始。1. % 占位符的核心概念与基础用法1.1 常用占位符类型与含义Python 中%占位符的核心逻辑是在字符串中用%加一个类型字母来标记位置然后用右侧的变量值去填充。最常见的几个占位符类型我直接列出来占位符目标类型典型使用场景%s字符串str最万能的占位符任意对象都可以先转成字符串再填入%d整数int用于整数格式化浮点数会自动截断为整数部分%f浮点数float默认保留 6 位小数%x/%X十六进制整数用于输出小写/大写十六进制%o八进制整数输出八进制字符串%e/%E科学计数法输出用 e/E 表示的浮点数%r原始表示repr调用 repr() 而不是 str()适合调试这里重点讲一下%s为什么“万能”它对任意 Python 对象都会调用其__str__()方法如果对象没有定义这个方法就会退化为repr()的默认实现。这意味着你完全可以把一个自定义类的实例直接塞进去输出结果是对象在 str 下的表现形式。不过要注意%s不会做隐式类型转换的“提醒”比如你传入一个 None它输出的是字符串None而不是报错。这在拼接日志时很方便但在要求严格数据类型的场景里反而容易掩盖问题。%d这里有个常见误解以为它接受浮点数时会四舍五入。实际上%d对于浮点数采取的是截断truncate而不是四舍五入%d % 3.7得到的是3而不是4。如果你确实需要四舍五入得用round()预处理或者直接用%f配合格式控制符。这一点在我实际面试候选人的时候经常拿来当考察点很多人都会在这里翻车。1.2 基本语法与传参方式%占位符的基本语法分两种元组传参和字典传参。先看元组传参name Alice age 25 # 多个占位符时用括号包起来按顺序匹配 print(My name is %s, and I am %d years old. % (name, age))左边字符串里有几个占位符右边元组就必须有几个元素顺序一一对应多一个少一个都会报 TypeError具体报错信息我后面专门讲。如果你只有一个占位符可以考虑不加括号直接写变量但为了代码统一和避免后续增加占位符时忘改括号我个人的习惯是一律写成(变量,)这种元组形式即使只有一个变量也带逗号。其实 Python 在单个变量时% value和%(value,)都是等价的但手工维护时括号更稳尤其是后续要往这个字符串里加新的占位符。再看字典传参data {name: Bob, score: 92.5} print(Student %(name)s got %(score)f in the exam. % data)这种写法在占位符里用括号包住字典的键名再在右侧传入字典占位符会按键名去字典里取对应的值。它的好处很明显占位符顺序打乱或者说字典里键的顺序和字符串里出现的顺序不一致都不影响结果同一个键在字符串里用了两次也只需要在字典里存一份。这在处理配置模板、需要多次复用同一变量的场景下特别实用。2. 进阶用法格式控制符详解2.1 宽度、精度、对齐与填充单一的%s或%d只能完成最基本的替换真正让%系列占位符强大的是它的格式控制符。语法结构可以概括为%[(映射键)][标志符][宽度][.精度]类型字母拿%8.2f来说8是总宽度包含小数点.2是小数位数f是浮点数类型。举几个我在实际项目里经常用的例子# 宽度控制右对齐总宽度占 10 个字符 print(%10s % hello) # 输出: hello左边5个空格 # 精度控制保留2位小数 print(%.2f % 3.14159) # 输出: 3.14 # 宽度精度总宽8小数2位 print(%8.2f % 3.14159) # 输出: 3.14 # 左对齐标志- 号 print(%-10s % hello) # 输出: hello 右边5个空格 # 补零 print(%05d % 42) # 输出: 00042这些细节单独看都很简单但组合在一起能解决很多格式排版问题。比如我做过一个命令行报表工具需要把几列数据按照固定宽度对齐输出用%-20s %-10d %8.2f这种模式可以直接一行搞定表格对齐不需要手工算空格数量。有个容易忽略的点%f的默认精度是 6 位小数这其实是 IEEE 754 浮点数打印策略的一个折中。如果你只写%f而不带精度输出的3.14会变成3.140000很多新手会以为这是 bug其实是格式控制的默认行为。想要去掉末尾多余的零可以考虑用%g它会自动在“小数形式”和“科学计数法”之间选择更短的那种显示方式。2.2 数字格式化技巧进制、千位分隔与符号控制除了宽度和精度%占位符还能做一些数字格式化的花活。第一个是进制转换这在实际编程里应用场景很多比如输出 RGB 颜色值、内存地址等# 十六进制输出 print(%x % 255) # 输出: ff print(%X % 255) # 输出: FF # 八进制输出 print(%o % 10) # 输出: 12 # 带进制前缀 format() 容易做到但 % 里没有直接选项需要手动拼接 print(0x%x % 255) # 输出: 0xff第二个是符号控制%d可以在正数前面显示加号% d则是在正数前显示空格print(%d % 42) # 输出: 42 print(%d % -42) # 输出: -42 print(% d % 42) # 输出: 42前面有一个空格 print(% d % -42) # 输出: -42不变的负号 # 配合右对齐可以让正负号位置对齐报表场景常用 print([%8d] % 42) print([%8d] % -42)第三个是千位分隔符。这里我得说句实话%系列并不原生支持千位分隔符它不像format()里{:,}那样的简洁语法。在 Python 3.6 里如果你用了%又想显示千位分隔最快的方式是结合format()先处理数字再拼接或者干脆换用 f-string。不过%在处理百分比时有一个天然优势——%%转义这种转义方式让模板字符串不会跟元组参数产生冲突progress 45 print(Progress: %d%% % progress) # 输出: Progress: 45%这个%%很容易被忽略我第一次写的时候漏掉了一个%结果程序直接报 ValueError: unsupported format character。就是因为%在字符串里是特殊字符想要输出字面意义的百分号必须写成两个。3. 与 format()、f-string 的横向对比3.1 三种格式化方式的选型逻辑Python 现在有三种主流的字符串格式化方式%占位符、str.format()、f-string。很多人问我到底该用哪个我一般会这样说新代码优先用 f-string维护老代码时能看懂%在特定场景下如 logging 模块惰性格式化%依然是最优解。先说 format()它在 Python 2.6 引入定位是替代掉%的一些短板支持关键字参数、支持访问对象属性、支持更复杂的格式规范比如千位分隔符、datetime 格式化。它的优点和缺点同样明显优点是功能全缺点是写起来啰嗦。同样的需求f-string 只需要一句f{name} is {age} years oldformat() 要写{} is {} years old.format(name, age)。f-string 的底层实现其实基于 format 协议所以在性能上比%和 format() 都更有优势。Python 3.6 引入 f-string 之后它在语法解析阶段就被编译成了向量化的字符串拼接不需要额外的一次函数调用开销。我在一段需要循环百万次的日志输出代码里实测过f-string 比%格式化快大约 10%~20%虽然单次差距很小但在循环累积下还是能感知的。表格对比一下三者的核心能力能力% 占位符format()f-string语法简洁度中等较繁琐最简洁运行时动态构造支持模板和变量可分离支持不支持必须是字面量关键字传参支持字典支持直接使用变量名访问对象属性不支持支持{obj.attr}支持f{obj.attr}性能较快较慢最快延迟求值支持配合 logging不支持不支持老代码兼容全部 Python 版本Python 2.6Python 3.6那为什么%还没被淘汰原因集中在延迟求值这个特性上。logging 模块的 format 参数即使传入Hello, %s % name也会在传入前就完成字符串替换那延迟求值就失效了。但真正推荐的写法是logging.info(Hello, %s, name)注意这里的占位符传给 logging由 logging 内部去处理格式化只有当这条日志确实要被输出时才会进行替换。这在日志级别过滤掉大量 DEBUG 信息时能省下不小开销。3.2 性能摸底到底谁的执行效率更高我在本机做过一个很粗糙的 benchmark测试三种方式拼接 100 万次字符串所需时间结果如下import timeit name Alice age 25 t1 timeit.timeit(%s is %d years old % (name, age), globalsglobals(), number1000000) t2 timeit.timeit({} is {} years old.format(name, age), globalsglobals(), number1000000) t3 timeit.timeit(f{name} is {age} years old, globalsglobals(), number1000000) print(f% 占位符: {t1:.4f}s) print(fformat(): {t2:.4f}s) print(ff-string: {t3:.4f}s)实测下来%占位符大约耗时 0.25 秒format() 约 0.35 秒f-string 约 0.2 秒。可以看到 f-string 最快%紧随其后format() 最慢。差异主要原因在于 format() 需要解析格式化字符串里的{}语法这个解析过程有开销。%不需要复杂的语法解析但代入元组参数时也要做一次元组遍历所以略慢于 f-string。不过说真的除非你在做热路径优化否则这点性能差异基本可以忽略。真正应该关注的不是 micro-benchmark 的数字而是代码的可读性和可维护性。我用%的场景基本只剩两类一类是 logging 模块的惰性求值另一类是维护老项目里已有的代码风格保持一致便于 review。4. 实操中的常见问题与排查技巧4.1 报错类型与排查方法我在日常开发和指导新人过程中总结出了%占位符最常出现的几类报错这里做成速查表方便你对照排查报错内容可能原因解决方案TypeError: not all arguments converted during string formatting占位符数量少于右侧元组元素数量删除多余变量或补齐占位符TypeError: not enough arguments for format string占位符数量多于右侧元组元素数量补齐右侧元组或减少占位符ValueError: unsupported format character X在字符串中出现了%后面跟着无法识别的字符把%写成%%或检查占位符类型字母拼写KeyError: name使用了映射键方式但字典里没有对应的键检查字典键名和占位符括号内的键名是否一致TypeError: %d format: a real number is required, not str类型不匹配比如给%d传了字符串转换类型为 int或用%sValueError: incomplete format字符串末尾出现了单独的%检查是否漏写了类型字母或需要转义%%这里面unsupported format character是最隐蔽的。很多 Python 新人写 SQL 拼接时比如SELECT * FROM table WHERE rate %s AND percent 10% % rate这里最后那个10%里的%会被误认为占位符开头自动去解析后面的或空格导致报错。切记字符串里要想输出字面百分号必须是%%。还有一个关于%s的细节如果右侧传入的元组只有一个元素但左侧出现了两个%s那就会触发 not enough arguments 错误。这看起来很明显但实际工作中当你用函数返回值直接塞入格式化字符串时很容易忽略返回的是元组还是单个值。我的调试经验是先用 Python 交互式环境单独 run 一次最小的复现场景再逐步套回真实代码中定位速度会快很多。4.2 踩坑记录与避坑经验第一个坑浮点数精度与%f的四舍五入行为。Python 的浮点数本身基于 IEEE 754用二进制表示十进制数会有精度误差所以%.2f在个别数字上会出现“意外进位”。比如print(%.2f % 2.675) # 输出 2.67而不是 2.68原因在于2.675在二进制里实际上是一个略微小于2.675的数存储为2.6749999999999998...四舍五入到两位小数自然变成2.67。这个坑在财务相关代码里尤其致命解决方案是使用Decimal或者先缩小到整数再运算from decimal import Decimal, ROUND_HALF_UP value Decimal(2.675) print(value.quantize(Decimal(0.01), roundingROUND_HALF_UP)) # 2.68第二个坑字符串中包含大量%的模板场景。比如在生成 HTML 模板或 CSS 样式文本时%频繁出现如果你用%占位符去格式化势必要把所有字面%全部写成%%非常容易漏改而漏改之后报错信息又不直观。我的建议是这种情况果断换成 f-string 或 format()避免在一堆需要转义的%里做“大家来找茬”。第三个坑多行字符串配合%时的缩进问题。如果你用三引号定义模板然后调用%格式化空格会原样保留在输出里。这在某些场景下不是问题但如果模板用于生成日志或报告会多出一堆额外缩进。处理方式一个是.strip()或.replace(\n , \n)另一个更优雅方案是textwrap.dedent()。第四个坑映射键方式处理用户输入时会容易触发 KeyError。如果在代码中动态构造字典然后再用%(key)s去格式化模板一旦用户输入或外部数据里少了某个键程序就会在你完全没预料到的地方抛 KeyError。这种场景我推荐用 dict 的get()方法预先补默认值或者用%加上collections.defaultdict来兜底。5. 实际应用场景与代码实战5.1 日志系统与按需格式化我个人接触最多%占位符的场景是 logging 日志系统。理论上 logging 是%风格最忠实、最合理的应用场景因为它的Logger.info(msg, *args)实现了惰性格式化。直接看代码import logging logging.basicConfig(levellogging.DEBUG) logger logging.getLogger(__name__) def process_user(user_id, name): # 注意这里不预先拼接而是把参数作为独立变量传给日志器 logger.debug(Processing user id%s name%s, user_id, name) # 后续处理逻辑... return True为什么logger.debug(... %s ..., user_id)比logger.debug(... %s ... % user_id)更好原因在于如果你把整个字符串先格式化好再传给 logger那么即使当日志级别是 INFO、DEBUG 信息不会输出你也白白付出了字符串拼接的开销。而使用惰性传参日志系统在内部确认这条日志需要输出时才会执行格式化。在高性能服务器日志场景里大量被过滤掉的 DEBUG 日志带来的开销会显著拖慢整体吞吐量。这个场景还有一个隐藏好处日志系统可以正确处理某些时间、异常对象等复杂类型。比如你直接传一个 exception 对象%s会调用str()得到异常的字符串表示如果使用%r则得到带有引号的repr()表示。调试时用%r往往能看到更多细节比如字符串里隐藏的换行符和空格。5.2 SQL 语句与安全边界很多初学 Python 连接数据库的人习惯用%直接拼接 SQL这是绝对需要警惕的。先看一个反面例子# 反面教材千万不要这样做 name input(请输入用户名: ) sql SELECT * FROM users WHERE name %s % name这段代码非常危险一旦用户输入admin OR 11拼出来的 SQL 就会变成SELECT * FROM users WHERE name admin OR 11直接把全部用户数据拖出来。这属于典型的 SQL 注入。%占位符并不能提供任何防注入能力因为它只是在字符串层面做替换所以请务必使用数据库驱动自带的参数化查询import sqlite3 conn sqlite3.connect(example.db) cur conn.cursor() name input(请输入用户名: ) # 正确的参数化查询用 ? 占位驱动负责转义和安全处理 cur.execute(SELECT * FROM users WHERE name ?, (name,)) rows cur.fetchall()MySQL 驱动 pymysql 中用的是%sPostgreSQL 的 psycopg2 用的是%s虽然看起来和字符串%占位符一样但它们走的不是 Python 字符串格式化而是数据库驱动内部的参数绑定机制两者千万不要混为一谈。实际经验里我最常碰到的坑是写代码时不小心在 SQL 字符串里用了%风格格式化导致参数被 Python 抢先替换然后把一个已经拼接好的字符串交给数据库驱动等于白费了参数化的保护。排查方式很简单如果你在 execute 调用前看到字符串变量已经包含了用户输入的内容就说明整个防线已经失效了。5.3 报表输出与对齐排版命令行工具、日志文件、文本报表中%占位符的对齐和宽度控制能力一直很能打。我第一次接触它的时候真觉得这玩意儿像是从 C 语言 printf 里继承来的遗老遗少但实际上手之后发现它在文本排版方面确实是无缝衔接。举个我实际做过的例子一个简单的库存报表products [ (apple, 120, 3.5), (banana, 45, 2.0), (cherry, 200, 5.25), ] # 表头 print(%-12s %8s %10s % (Product, Quantity, Price)) print(- * 34) for name, qty, price in products: print(%-12s %8d %10.2f % (name, qty, price))输出效果Product Quantity Price ---------------------------------- apple 120 3.50 banana 45 2.00 cherry 200 5.25这里%-12s表示左对齐并补足 12 个字符宽度%8d表示右对齐补足 8 个字符宽度%10.2f表示总宽度 10、保留两位小数。这种固定宽度的输出非常适合生成报表、目录表、日志摘要所有列都能整齐对齐不需要手工计算空格数量。我个人的经验是在写这种对齐格式时先定好每一列的宽度再用实际数据试跑一遍总有一些名字超长的条目会把列挤乱。处理办法有两种一种是 truncate 字符串到固定长度再补省略号另一种是根据数据动态计算最大宽度。动态宽度用%占位符也能实现因为占位符的宽度部分可以用变量嵌入col_width 15 print(%*s % (col_width, hello)) # 等价于 %15s这个*语法很多人不知道它表示宽度在右侧元组中动态指定。这样写报表代码时可以先用 max 函数算出最长条目再动态生成格式化模板非常实用。5.4 模板化配置与字典映射除了日志、SQL、报表%占位符在配置模板和消息模板上也有独到之处。我最常用的能力是字典映射因为它可以优雅处理“同一个模板里同一个变量出现多次”的问题。举一个实际案例邮件模板email_template Dear %(name)s, Your order #%(order_id)s has been shipped. Track number: %(tracking_number)s Estimated delivery time: %(delivery_time)s Thank you for shopping with us! %(shop_name)s order_info { name: 张三, order_id: NO.2025012012001, tracking_number: SF1234567890, delivery_time: 2025-01-25, shop_name: 极客小铺, } print(email_template % order_info)如果你用%s按位置传参模板里同一个变量出现两次就得在元组里重复写两遍非常麻烦。而字典映射一次定义、随处引用清晰得多。这种模式在 Web 框架的邮件发送、通知消息、报告生成中都很常见。还有一个比较进阶但很实用的技巧是把模板放在配置文件中运行时加载再格式化# 假设 config.conf 里有一行 # welcome_msg Welcome back, %(username)s! You have %(unread_count)d new messages. with open(config.conf, r, encodingutf-8) as f: template_str f.read() user_context { username: alice, unread_count: 3, } print(template_str % user_context)这种做法的好处是文案和代码解耦运营同事可以直接改配置文件里的模板不需要动代码。不过要注意%占位符本身不校验模板里用到的键是否都已经在字典中提供如果在配置模板中新加了一个%(new_field)s而代码忘了更新 context运行时会直接 KeyError。为这个问题我一般会在代码中做一个显式的模板校验import re def validate_template(template, context): # 提取所有占位符键 keys re.findall(r%\((\w)\)[a-z], template) missing [k for k in keys if k not in context] if missing: raise ValueError(f模板缺失字段: {missing}) validate_template(template_str, user_context)这个函数很简单但避免了很多线上环境才暴露的 KeyError。说到底%占位符虽然老但在模板化场景里依旧有用武之地问题只在于我们要想清楚边界并且主动补上一些校验机制。结尾我在实际工作中见过不少把%占位符用得很飘逸的人也见过因为一个小%符号排查半天的场景。说到底占位符只是工具工具没有新旧贵贱只有合不合适。新代码我会推荐 f-string 和 format()但碰到 logging 惰性求值、老项目维护、动态模板配置%系列依然有它在工程上的位置。最后分享一个小技巧在写格式化代码之前先在交互式环境里跑一遍你的模板和参数确认没有 TypeError 和 ValueError 再粘到正式代码里能省下不少排错时间。格式化这看似鸡毛蒜皮的事情反而最能看出一个程序员对细节的把控。