做 Web 和自动化相关开发的同学迟早都会碰到一个看起来简单但藏了不少坑的需求把一张图片从 Python 代码里变成一长串文本然后再把这串文本塞进 JSON、写进数据库、拼到接口返回值里或者直接扔给前端渲染。这里面的关键组合就是 Python、PIL 和 Base64 字符串。这篇内容要做的就是把这套“图片转字符串、字符串转图片”的完整链路给你讲透包括怎么用 Pillow 处理图片、怎么用 Base64 编码、你写的时候会撞上哪些典型的坑以及最后怎么在真实项目里落地。不管你是刚接触 Python 的小白还是已经写过几年业务代码但很少碰图像处理的开发者这篇文章都能让你拿过去直接“抄作业”。先说一下我自己的使用场景。前两年做内部系统时经常需要把各种临时生成的验证码、订单截图、图表预览图从前端传到后端或者从后端返回到前端。有同事图省事直接把图片以文件路径传来传去结果部署到不同服务器之后路径全乱图片全挂。后来我把方案统一成“PIL 生成图片 → Base64 字符串 → 接口传输”虽然数据体积变大了一点但跨平台、跨服务、跨进程传递全都顺了。今天就把这个过程中积累的经验完整分享出来。1. 为什么要把图片变成Base64字符串场景与原理1.1 哪些现实场景需要图片转Base64很多人第一反应是我直接把图片文件传过去不就好了为什么要转字符串会这么问是因为你还没被“跨系统传输图片”这件事折磨过。实际开发中遇到最多的几类情况是这样的第一类是接口传输。你做前后端分离或者对接第三方 API有时候就是没有办法直接在 multipart 表单里塞二进制文件或者接口早就定义成了 JSON 格式。这个时候 Base64 字符串就是最省事的通用格式随 JSON 一起走不需要额外解析文件流。第二类是数据库存储。有些场景你不希望把图片落成磁盘文件而是想直接以文本字段存进数据库比如存一个小图标、一张小程序码、一个签名图。虽然我一直不建议把大图存数据库但小图片存文本字段确实方便尤其配合定时任务、缓存系统省掉了一堆文件服务器的烦恼。第三类是在线预览和邮件嵌入。HTML 里的 data URI 大家应该见过形如data:image/png;base64,....把图片 Base64 之后拼上这个前缀前端直接放进img标签的 src 属性就能显示不用发请求、不用接口、不用下载。邮件客户端里很多内嵌图也是这么干的否则你发出去的邮件对方收到时经常看不到图片。第四类是图片在内存里生成、压根不需要落盘。你用 Pillow 动态画图、做验证码、给图片加水印生成出来的对象只在内存中如果转成 Base64 字符串就可以把这个结果直接打成日志、发给消息队列、或者存进 Redis。整个过程不走磁盘干净利落。1.2 Base64的本质把二进制包装成文本但别指望它压缩Base64 这个概念对新手来说好像很神秘其实说白了它就是一种把二进制数据变成 ASCII 文本的编码规则。原理是把每 3 个字节24 bit拆成 4 组每组 6 bit然后映射到A-Z a-z 0-9 /这 64 个可打印字符上不够 3 字节的末尾补。用生活里的例子类比二进制数据就像你要寄送的精密零件网络和很多存储系统并不是一个适合裸寄零件的环境于是你把它放进一个统一的、标准尺寸的防震包装盒里这个包装盒就是 Base64 编码。对方收到后只需要拆开包装解码就能还原成原来的零件。整个过程玩的是“重新包装”不产生任何压缩效果反而因为每 3 字节变成 4 个字符体积会膨胀约 33%。这个“膨胀 33%”会带来什么实际影响一张 10MB 的图片转成 Base64 字符串之后大约是 13.3MB如果是对一个大视频或者大型二进制流做这种转换内存和传输开销都会明显上升。所以你在工程化的时候必须心里有数这是一笔数据体积的“附加税”换取的是传输和存储上的极大便利。后面第 6 节我会专门讲怎么把这笔“税”省着点交。2. Pillow转Base64的核心操作从Image对象到字符串2.1 最简代码转换三步走先给出一段可以直接跑起来的最小完整示例。这里强调一点现在的项目里直接 pip install PIL 是装不上的因为最初的 PILPython Imaging Library早已停止维护大家现在用的是它的兼容分支 Pillow导入语句仍然是from PIL import Image。你只要 pip install Pillow 就行。from PIL import Image import base64 import io # 第一步用Pillow打开图片文件得到一个Image对象 img Image.open(demo.png) # 第二步把Image对象保存到内存缓冲区而不是保存到磁盘 buffer io.BytesIO() img.save(buffer, formatPNG) # 第三步把缓冲区里的二进制数据取出来做Base64编码再转成字符串 base64_str base64.b64encode(buffer.getvalue()).decode(utf-8) print(base64_str)核心就是这么三行逻辑打开 → 写入内存 → 编码。很多网上的教程会教你“先把图片保存成临时文件再读文件再编码”虽然也能跑通但会留下两个问题一是产生临时磁盘文件污染系统二是在高并发或者容器环境下反复读写磁盘性能很差。而io.BytesIO()是在内存里模拟了一个文件对象你的图片数据不落盘整个过程完全在内存中完成干净且高效。2.2 BytesIO为什么是必需品理解BytesIO是理解整个转换流程的关键。Pillow 的Image.save()方法需要接收一个文件路径或者一个文件对象。文件对象除了真实磁盘文件open(xxx.png, wb)返回的对象也可以是内存虚拟文件。io.BytesIO()创建的就是这样一个虚拟文件你用save()往里面写数据之后用getvalue()可以把里面所有的字节一次性取出来。为什么不能直接用img.tobytes()呢这个问题很多人问过。Image.tobytes()返回的是图像的原始像素数据也就是说它是图像解码后的裸 RGB/RGBA 数据不包含 PNG 或 JPEG 的压缩编码信息。直接把这段裸数据转成 Base64不仅体积巨大一张图片的像素数据远远大于压缩后的文件数据而且别人拿到之后无法直接作为图片文件打开还需要额外知道尺寸、通道数、颜色空间等一大堆元数据。这就是为什么我们必须经过img.save(buffer, formatPNG)这一步它会把像素数据按 PNG 规则压缩编码生成是完整的、标准可识别的图像文件格式。2.3 保存格式必须显式指定format参数的门道img.save(buffer, formatPNG)里的format参数最好永远不要省略。为什么因为 Pillow 自动判断格式的逻辑通常是靠文件扩展名来的但BytesIO没有文件名如果你不指定format保存时大概率会直接报错或者保存成默认的格式结果和你的预期不一致。所以一个实用的习惯是永远显式传formatPNG或formatJPEG或formatWEBP。这里我把不同格式的特征列个表格方便你按场景选格式是否支持透明通道压缩类型典型体积适合场景PNG支持无损中等偏大图标、截图、需要透明的图JPEG不支持透明有损较小照片、无明显边缘的图WEBP支持透明有损/无损可选通常最小Web前端展示、需要极致压缩如果你把 RGBA 模式的图用 JPEG 格式保存Pillow 会报错或者强制丢透明通道这个我放到下一节单独讲因为这是新手最容易栽的第一个坑。3. 转换过程中的常见事故模式、格式与缓冲区3.1 RGBA保存成JPEG模式转换不能省代码跑通了之后你很快会遇到第一个诡异场景。某天你生成了一张带透明背景的图片心里想着“我要把它转成 JPEG 格式的 Base64”结果一执行Pillow 直接甩给你一个异常OSError: cannot write mode RGBA as JPEG这个错误的原因很简单JPEG 格式本身不支持 alpha 透明通道它只有 RGB 三个颜色通道。而 PNG 支持RGBA 模式恰好就是要写 PNG 的。解决方案就是在保存之前手动转模式img img.convert(RGB) buffer io.BytesIO() img.save(buffer, formatJPEG, quality85)这里有个细节要提醒你透明区域在转换时会被填充成黑色还是白色取决于你的图片内容。绝大多数情况下透明背景转 JPEG 后直接变黑这是很多人不满意的地方。如果你希望透明区域变成白色背景那就不能直接.convert(RGB)得先创建一个白底 RGB 画布再把原图贴上去from PIL import Image background Image.new(RGB, img.size, (255, 255, 255)) background.paste(img, maskimg.split()[-1]) # 用alpha通道作为蒙版 img background这段代码我是踩过一次坑才记牢的。平时做验证码、小程序码截图时透明背景转白底几乎都是必须的否则前端显示出来就是一团黑疙瘩。3.2 Base64里的换行符和数据前缀要怎么处理第二个大坑是字符串“不干净”。来自不同来源的 Base64 字符串格式可能不同直接拿去解码会出问题。第一种情况是标准库的base64.encodebytes()生成的字符串会每隔 76 个字符插入一个换行符如果你用b64encode()则不会。但是当你在项目里读到别人代码生成的字符串或者从日志、数据库、配置文件里拿到一段 Base64 时里面可能藏了不少换行和空格。第二种情况是带前缀的 data URI。很多前端代码直接就把data:image/png;base64,xxxx整个字符串传给了后端。这时候如果你直接base64.b64decode(whole_string)会抛异常或者返回一堆乱码数据因为前缀部分并不是合法的 Base64 字符。通用的处理方案如下import base64 import re def clean_base64(s: str) - str: # 去掉 data URI 前缀 if s.startswith(data:): s s.split(,, 1)[-1] # 去掉空白字符 s re.sub(r\s, , s) return s def b64_to_bytes(s: str) - bytes: cleaned clean_base64(s) return base64.b64decode(cleaned)更稳妥一点的做法是用base64.b64decode(s, validateFalse)。validateFalse是默认值它会在解码时忽略非字母表字符比如换行符。但为了可读性和避免意外我建议还是自己做清洗因为有时候字符串里混进了不合理的字符b64decode的“宽容模式”会把错误也吞掉让你找不到真正的问题在哪。3.3 BytesIO的“指针”陷阱getvalue还是read第三个坑比较隐蔽但它能让你的 Base64 字符串变成一截空串。先看这段代码buffer io.BytesIO() img.save(buffer, formatPNG) # 错误写法 data buffer.read() base64_str base64.b64encode(data).decode(utf-8)如果在这之前你已经在buffer上做过一次seek(0)和read()那没问题但如果只是save()之后直接read()你会震惊地发现data是b。原因在于save()写完之后文件指针停在缓冲区末尾也就是说文件的“读写头”已经移动到最后一个字节的后面了。此时调用read()从当前位置一直读到末尾自然只能读到空。正确做法是使用getvalue()它会返回缓冲区的全部内容完全不管你当前文件指针在哪儿base64_str base64.b64encode(buffer.getvalue()).decode(utf-8)或者使用seek(0)配合read()buffer.seek(0) data buffer.read()除非你要在这个缓冲区上做多次读写否则我个人建议一律用getvalue()简洁安全不容易出幺蛾子。3.4 如果图片里有中文文字PIL默认字体直接翻车这里额外再说一个和 PIL 转换强相关的高频问题你要在图片上画文字然后再转 Base64。很多人在 Pillow 里直接用默认字体ImageFont.load_default()画英文还行一画中文就出现一堆方框“□□□□”。这不是编码问题而是 Pillow 内置默认字体根本不包含中文字形。解决办法是加载系统中文字体文件。Windows 上常见的是C:/Windows/Fonts/msyh.ttc微软雅黑macOS 上是/System/Library/Fonts/PingFang.ttcLinux 上要看你装了什么中文字体常见路径是/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc。from PIL import ImageFont font ImageFont.truetype(C:/Windows/Fonts/msyh.ttc, 32)加载成功后再用draw.text()画中文最后按前面的流程保存成 PNG 再转 Base64出来的字符串前端拿到就能显示正常。很多时候我们排查“Base64图片显示成乱码”“图片上文字是乱码”根源不是转换过程而是图片生成时字体加载失败。4. 反向操作把Base64字符串还原成图片4.1 解码后从BytesIO重新打开处理完图片转字符串之后你大概率还需要做反向操作收到一段 Base64 字符串把它还原成图片对象或者存成文件。和正向流程相反核心就三步解码 → 放进 BytesIO → 用 Image.open 读取。import base64 import io from PIL import Image def base64_to_image(base64_str: str) - Image.Image: # 清洗字符串 if , in base64_str and base64_str.startswith(data:): base64_str base64_str.split(,, 1)[-1] base64_str base64_str.strip() # 解码得到二进制数据 img_bytes base64.b64decode(base64_str) # 丢进BytesIO让Pillow从内存中解析 img Image.open(io.BytesIO(img_bytes)) return img注意这里Image.open()并不会立刻把图片的全部像素数据加载进内存它有一个“懒加载”机制读取文件头、尺寸、格式等信息之后等真正用到像素比如img.load()、img.save()、img.size之外的像素操作才会完整解码。这在处理大批量图片时能省不少内存但也会带来一个副作用BytesIO缓冲区的生命周期必须保持到图片真正被加载或复制为止。也就是说你不能在一个函数里打开Image.open(io.BytesIO(img_bytes))接着函数结束了BytesIO被回收然后再去用img.load()这样是会出问题的。一个粗暴但稳妥的办法是打开后立刻复制一份像素数据img Image.open(io.BytesIO(img_bytes)).copy().copy()会强制把图片完整解码成内存中的独立对象此时 BytesIO 的生命周期就不再影响后续使用了。代价是图片数据会完整加载到内存大图会吃不少内存但换来了心安。4.2 保存到磁盘的正确姿势如果只是想把 Base64 还原的文件以 PNG/JPEG 形式存到磁盘上最简单的做法是with open(restored.png, wb) as f: f.write(base64.b64decode(cleaned_str))这样写出来的文件就是标准的图片文件能打开、能预览。不用绕一圈再去用img.save()因为解码后的bytes就是原始图片文件的全部字节直接落盘最效率。当然如果你还要对还原出来的图做处理比如改大小、加滤镜那就用 4.1 节的Image.open(io.BytesIO(...))方案。4.3 不要忽略字符串清洗我在实际接口联调里见过最快翻车的情况就是前端传过来的 Base64 字符串里带了一段前缀data:image/jpeg;base64,后端同事没处理直接解码结果整个程序报错。也有从 Excel 单元格里读出来的字符串自动换行卡了你半天。所以无论是正向还是反向写一个clean_base64()工具函数放在公共模块里是个非常划算的小投资。5. 真实场景落地data URI、HTTP接口和数据库存储5.1 前端预览专用data URI拼法在前后端分离的项目里我们经常要生成一个验证码图片回显给前端。传统做法是后端把图片接口暴露出去前端用img src/captcha去加载。但其实也有不少项目直接用 Base64 字符串返回把整个图片的 data URI 发给前端。data URI 的拼法非常简单data_uri data:image/png;base64, base64_str前端拿到之后直接img.src data_uri就能显示。这里的重点是image/png必须和你保存图片时用的格式对应。如果你保存的是 JPEG那就要拼data:image/jpeg;base64,...否则部分浏览器会拒绝渲染或者显示异常。我在项目中会动态判断格式format_map { PNG: image/png, JPEG: image/jpeg, WEBP: image/webp, } def image_to_data_uri(img: Image.Image, fmt: str PNG) - str: buffer io.BytesIO() if fmt.upper() JPEG and img.mode ! RGB: img img.convert(RGB) img.save(buffer, formatfmt.upper()) mime format_map.get(fmt.upper(), image/png) return fdata:{mime};base64,{base64.b64encode(buffer.getvalue()).decode()}5.2 HTTP接口传图Base64字段还是二进制流既然做接口设计迟早要面临一个选择图片用 Base64 放在 JSON 里传还是用 multipart/form-data 走二进制流我的经验是分场景。如果是小图片几十KB到几百KB传 Base64 非常方便因为传输、日志、mock、调试都极其直观任何 HTTP 调试工具都能直接看。但如果图片经常超过 1MB甚至几 MB我建议还是老实走二进制上传接口因为 33% 的体积膨胀在带宽成本上不是小数而且 JSON 字段本身对大字符串的解析也有额外开销。如果要传 Base64比较推荐的 JSON 结构一般是{ image: data:image/png;base64,..., filename: demo.png }后端把多个图片字段放在一个 JSON 里也支持批量上传。注意如果字段里已经带了 data URI 前缀后端不要重复拼前缀如果不带后端要根据扩展名或者图片实际格式判断 MIME 类型。这个统一约定一定要写在接口文档里我在项目里吃过好几次“我加前缀你不识别、你还加前缀重复了”的误会。5.3 数据库存储的取舍关于图片塞数据库我的态度是有条件就别塞没条件就只塞小图。把 Base64 字符串直接存进 MySQL 的 TEXT 字段或者 MongoDB 的字符串字段确实省事——不折腾文件服务器、不搞对象存储、也避免了应用多副本之间文件不同步的问题。但你必须注意到两个代价第一是体积。原本 100KB 的图片存成 Base64 后约 133KB如果你存一万张额外多出来 330MB 的存储空间后面备份、迁移、查询都会变慢。第二是渲染性能。前端从数据库拎出来一整个大字符串再在前端解码渲染体验远不如直接用对象存储 URL 走 CDN。所以我的建议是只把极小图标、缩略图、临时验证码这类的图片用 Base64 存数据库大图一律走文件存储或对象存储数据库里只存 URL 或者对象存储的 key。这是性能和代码复杂度综合下来最平衡的路线。5.4 拼接一个完整的上传工具函数把前文的所有逻辑整合起来我日常项目里常用的工具函数长这样import base64 import io import re from PIL import Image def clean_base64(s: str) - str: if s.startswith(data:): s s.split(,, 1)[-1] return re.sub(r\s, , s) def pil_image_to_base64(img: Image.Image, fmt: str PNG, **save_kwargs) - str: if fmt.upper() JPEG and img.mode ! RGB: img img.convert(RGB) buffer io.BytesIO() img.save(buffer, formatfmt.upper(), **save_kwargs) return base64.b64encode(buffer.getvalue()).decode(utf-8) def base64_to_pil_image(s: str) - Image.Image: img_bytes base64.b64decode(clean_base64(s)) return Image.open(io.BytesIO(img_bytes)).copy() def base64_to_bytes(s: str) - bytes: return base64.b64decode(clean_base64(s))另外给你一个经常用到的自定义 kwargs 示例如果保存 JPEG 想控制质量就调用pil_image_to_base64(img, JPEG, quality80)想保存 WebP 并设置无损可以pil_image_to_base64(img, WEBP, losslessTrue)。**save_kwargs会被直接传给img.save()这就是灵活性的来源。6. 性能与工程化别等大图教做人6.1 先缩后编用thumbnail控制体积如果你要认真使用这个方案最后一定要解决的问题是图片太大Base64 字符串太长接口慢、前端卡、日志被刷屏。我推荐的做法是在编码之前先做一次缩放。Pillow 里最常用的是thumbnail()它会在保持宽高比的前提下把图片最长边缩到指定尺寸并且直接修改原对象img.thumbnail((1024, 1024), Image.Resampling.LANCZOS)Image.Resampling.LANCZOS是当前 Pillow 里质量最好的缩放算法之一在高分辨率原图缩小时观感损失小。注意thumbnail()只缩小、不放大如果图片本身小于 1024×1024它不会把图变大这一点非常贴心。也有不少教程推荐resize((700, 500))但resize会让你手动指定精确尺寸很容易破坏宽高比导致图片变形。日常使用我都优先用thumbnail()只有当业务明确要求固定尺寸的封面图时才用resize()加ImageOps.fit()裁剪填充。6.2 JPEG质量参数quality与optimize的实测心得选完格式压缩还有不少文章可做。JPEG 的核心参数是quality取值范围 1 到 95默认 75。我在实际项目里测试过对于大多数界面截图和照片quality80左右肉眼几乎看不出区别但体积比默认 75 差距不大如果把quality降到 60体积可以再降 30% 左右细节边缘开始有轻微损失适合用在缩略图上。还有两个参数值得认识。optimizeTrue会让编码器做更细致的优化体积能进一步降一点但编码速度会变慢progressiveTrue会生成渐进式 JPEG在低速网络下用户体验更好占用的体积基本不变。如果这份 Base64 数据要传给前端展示我个人习惯用quality80, optimizeTrue, progressiveTrue速度和体积综合表现都不错。PNG 就没那么多调参空间了它是无损格式体积主要取决于图像内容。真需要压缩 PNG 时可以转成 WebP 无损模式通常能比 PNG 小 20% 左右img.save(buffer, formatWEBP, losslessTrue)WebP 对现代浏览器的支持已经非常好如果是内部系统或者可控浏览器环境直接用 WebP 是性价比很高的选择。6.3 内存峰值管理批量处理时别一口气全干批量处理图片转 Base64 时最容易发生的是内存爆炸。原因很简单你每处理一张大图图片原始像素数据加编码缓冲区的总和可能超过图片文件的十几倍。一张 5000×5000 的 PNG文件可能只有 2MB但解码后在内存里的 RGBA 原始数据是 5000×5000×4 100MB再叠加编码后的 BytesIO 缓冲区内存瞬间就上去了。应对策略主要有三条第一批量任务不要并发开太高。如果你用的是进程池默认并发数改成 CPU 数的一半或者经验值 4~8避免多张大图同时抢占内存。第二处理完一张立刻释放引用。不要把所有 Image 对象或 Base64 字符串都攒在一个列表里。写循环时最好处理完就存出去或传出去。如果你用的是 Jupyter Notebook 这种自带变量保留的环境特别容易忽略这一点变量越堆越多。第三对大图先缩略再编码。这条和第 6.1 节呼应缩略本身就是最好的内存优化。一个 1024×1024 的 RGB 图原始像素数据只有 3MB 左右怎么处理都不会太失控。6.4 什么时候真的不该用Base64讲了这么多最后必须说点劝退话。有几种场景我强烈不建议用 Base64一是大文件传输。比如视频、压缩包、安装包你宁可花时间去搭文件服务或者对象存储也不应该用 Base64 徒增 33% 的体积和带宽。二是需要频繁读写的高性能缓存场景。Base64 编解码本身有 CPU 开销如果你每秒处理几千张图这成本不容忽视。能用二进制直接用二进制Redis 的 string 类型也支持存储 bytes不需要转文本。三是图片要长期存储且数量巨大。存对象存储给文件一个 key比存百万级 Base64 字符串在数据库里要稳健得多。数据库字段再宽也有长度限制超长字符串写入、索引、备份都会出问题。这套方案最适合的领域还是小体积图片的跨系统传输、动态图片的接口返回、前端 table 预览、邮件和 Markdown 内嵌图。边界清楚了用起来就不纠结。至少在我自己的项目里这一套“PIL BytesIO Base64”的组合已经稳定跑了好几年。最后再分享一个小经验转换字符串之前先用img.size和img.mode打印出来看一眼很多奇怪问题其实就是这两个属性没符合预期。把最基础的信息确认好你的图片转换之路会顺畅不少。