Python 中 Base64 编解码完整指南

← 返回博客

Python 中 Base64 编解码完整指南

· 5 分钟阅读

Python base64 模块概述

Python 标准库中的 base64 模块提供了完整的 Base64 编解码功能，无需安装任何第三方包。该模块支持多种 Base64 变体，包括标准 Base64、URL 安全的 Base64（Base64URL）、以及用于 MIME 邮件的变体。

与 JavaScript 不同，Python 的 base64 模块操作的是 bytes 类型，而非字符串。这是因为 Python 3 严格区分了文本（str，Unicode 字符串）和二进制数据（bytes）。理解这一点对于正确使用 base64 模块至关重要。

基本编解码用法

import base64

# 编码字符串 / Encode a string
text = "Hello, World!"
# 先将字符串转为 bytes / First convert string to bytes
encoded = base64.b64encode(text.encode('utf-8'))
print(encoded)          # b'SGVsbG8sIFdvcmxkIQ=='
print(encoded.decode()) # 'SGVsbG8sIFdvcmxkIQ=='

# 解码 / Decode
decoded_bytes = base64.b64decode('SGVsbG8sIFdvcmxkIQ==')
decoded_text = decoded_bytes.decode('utf-8')
print(decoded_text)     # 'Hello, World!'

# 编码中文 / Encode Chinese text
chinese = "你好，世界！"
encoded_cn = base64.b64encode(chinese.encode('utf-8'))
print(encoded_cn.decode()) # '5L2g5aW977yM5LiW55WM77yB'

注意 b64encode() 接受 bytes 类型并返回 bytes 类型。如果需要字符串，调用 .decode('ascii') 或 .decode()（默认 UTF-8，但 Base64 输出只包含 ASCII 字符）即可。

编解码文件

import base64

# 将图片文件编码为 Base64 / Encode image file to Base64
with open('image.png', 'rb') as f:
    image_data = f.read()
    encoded = base64.b64encode(image_data).decode('ascii')
    print(f"data:image/png;base64,{encoded}")

# 将 Base64 字符串解码并保存为文件
# Decode Base64 string and save as file
def decode_to_file(base64_str, output_path):
    data = base64.b64decode(base64_str)
    with open(output_path, 'wb') as f:
        f.write(data)
    print(f"Saved {len(data)} bytes to {output_path}")

decode_to_file(encoded, 'output.png')

关键点：读取二进制文件时必须使用 'rb' 模式（二进制读取），写入时使用 'wb' 模式（二进制写入）。如果使用文本模式 'r'，Python 会尝试将文件内容解释为文本，导致二进制数据损坏。

URL 安全的 Base64 编解码

import base64

data = b'\xfb\xff\xfe'

# 标准 Base64（包含 + 和 /）
# Standard Base64 (contains + and /)
std = base64.b64encode(data)
print(std)     # b'+//+'  (举例，实际值根据数据而定)

# URL 安全 Base64（+ 替换为 -，/ 替换为 _）
# URL-safe Base64 (+ replaced with -, / replaced with _)
url_safe = base64.urlsafe_b64encode(data)
print(url_safe) # b'-__-'

# URL 安全 Base64 解码
# URL-safe Base64 decoding
decoded = base64.urlsafe_b64decode(url_safe)
print(decoded == data)  # True

# 处理无填充的 Base64URL（如 JWT）
# Handle unpadded Base64URL (like JWT)
def decode_jwt_part(base64url_str):
    # 补全填充
    padding = 4 - len(base64url_str) % 4
    if padding != 4:
        base64url_str += '=' * padding
    return base64.urlsafe_b64decode(base64url_str)

处理 Base64 解码错误

Python 的 base64.b64decode() 对输入的要求比较严格，遇到非法字符会抛出 binascii.Error 异常。可以传入 validate=False（默认）让函数忽略非法字符，或使用 validate=True 强制校验。

import base64
import binascii

def safe_b64decode(s):
    try:
        # 添加填充并解码 / Add padding and decode
        if isinstance(s, str):
            s = s.encode('ascii')
        # 补全填充
        s += b'=' * (4 - len(s) % 4)
        return base64.b64decode(s)
    except (binascii.Error, ValueError) as e:
        print(f"Decode error: {e}")
        return None

result = safe_b64decode('SGVsbG8')
print(result)  # b'Hello'

在 Web 框架中使用 Base64

在 Flask 或 Django 等 Web 框架中，Base64 常用于处理 HTTP Basic Auth 或接收前端上传的图片数据。以下是 Flask 中解析 Basic Auth 头的示例：

from flask import request
import base64

def get_basic_auth():
    auth_header = request.headers.get('Authorization', '')
    if not auth_header.startswith('Basic '):
        return None, None

    try:
        credentials = base64.b64decode(
            auth_header[6:]
        ).decode('utf-8')
        username, password = credentials.split(':', 1)
        return username, password
    except Exception:
        return None, None

注意 split(':', 1) 中的 1 参数非常重要：它确保只在第一个冒号处分割，允许密码中包含冒号（这是合法的密码字符）。

Base64 与字节流操作

Python 的 base64 模块还提供了流式处理接口，适合处理大型文件。base64.encodebytes() 和 base64.decodebytes() 会自动每 76 个字符插入换行符（符合 MIME 标准），适合生成电子邮件附件格式的 Base64 数据。

import base64

# MIME 格式（每76字符换行）/ MIME format (newline every 76 chars)
with open('document.pdf', 'rb') as f:
    data = f.read()
    mime_base64 = base64.encodebytes(data)
    print(mime_base64[:100])  # 查看前100字节

encodebytes() 与 b64encode() 的区别在于前者输出包含换行符，而后者输出的是无换行的连续字符串。在生成 API 请求体时应使用 b64encode()，而在生成 PEM 证书或 MIME 附件时应使用 encodebytes()。

立即尝试在线工具，无需安装，免费使用。

打开工具 →