在 Python 中处理包含中文字符的 URL 编码（urlencode），需要特别注意编码格式，确保中文字符能被正确转换成 URL 安全的格式。

核心要点：

1. 使用 urllib.parse 模块：这是 Python 标准库中用于处理 URL 编码和解码的模块。
2. 指定编码格式：必须明确告诉 urlencode 函数使用哪种编码（通常是 'utf-8'）来处理中文字符，如果不指定，它可能会使用系统的默认编码，这在不同环境下可能导致不一致甚至错误的结果。
3. 处理字典或序列：urlencode 主要用于将字典或 (键, 值) 序列列表转换为 URL 查询字符串。

对字典进行编码（最常用）

当你需要将一组参数（如 {'name': '张三', 'city': '北京'}）构造成 URL 查询字符串（如 name=%E5%BC%A0%E4%B8%89&city=%E5%8C%97%E4%BA%AC）时，使用字典。

from urllib.parse import urlencode
# 1. 准备包含中文字符的字典
params = {
    'name': '张三',
    'city': '北京',
    'message': '你好，世界！'
}
# 2. 使用 urlencode 进行编码
# 关键：指定 quote_via 或直接在字符串中处理，但最可靠的是确保字典值已经是 bytes 或指定编码
# 最简单直接的方式是确保字符串在传入前是已编码的，或者使用 safe 参数
# 推荐做法：先对每个值进行编码，再传入 urlencode
# 方法 A (推荐): 先手动编码每个值
# 这种方式最清晰，可控性最强
encoded_params = {
    'name': '张三'.encode('utf-8'),
    'city': '北京'.encode('utf-8'),
    'message': '你好，世界！'.encode('utf-8')
}
query_string_a = urlencode(encoded_params)
print(f"方法A结果: {query_string_a}")
# 输出: 方法A结果: name=%E5%BC%A0%E4%B8%89&city=%E5%8C%97%E4%BA%AC&message=%E4%BD%A0%E5%A5%BD%EF%BC%8C%E4%B8%96%E7%95%8C%EF%BC%81
# 方法 B (更简洁): 使用 urlencode 的 `doseq` 和 `safe` 参数，但核心是确保编码正确
# 直接传入字符串，并告诉 urlencode 使用 'utf-8' 编码
query_string_b = urlencode(params, encoding='utf-8')
print(f"方法B结果: {query_string_b}")
# 输出: 方法B结果: name=%E5%BC%A0%E4%B8%89&city=%E5%8C%97%E4%BA%AC&message=%E4%BD%A0%E5%A5%BD%EF%BC%8C%E4%B8%96%E7%95%8C%EF%BC%81
# 方法B更简洁，是现代Python（3.x）中的推荐方式。

解释：

• encoding='utf-8'：这是最关键的部分，它告诉 urlencode 函数，在将字典中的值（字符串）转换为 %xx 格式时，使用 UTF-8 编码规则。
• urlencode 会自动处理键和值，用 & 连接键值对，用 连接键和值。
• 输出的 %E5%BC%A0%E4%B8%89 "张三" 在 UTF-8 编码下的十六进制表示。

对序列（列表）进行编码

当你有一组 (键, 值) 元素的列表时，可以使用列表。

from urllib.parse import urlencode
# 1. 准备包含中文字符的 (键, 值) 序列列表
params_list = [
    ('name', '李四'),
    ('city', '上海'),
    ('hobby', '编程')
]
# 2. 使用 urlencode 进行编码，同样需要指定编码
query_string = urlencode(params_list, encoding='utf-8')
print(f"序列编码结果: {query_string}")
# 输出: 序列编码结果: name=%E6%9D%8E%E5%9B%9B&city=%E4%B8%8A%E6%B5%B7&hobby=%E7%BC%96%E7%A8%8B

完整示例：构建一个完整的 URL

这是一个非常常见的实际应用场景。

from urllib.parse import urlencode, urlparse, urlunparse
# 1. 定义API的基础URL和参数
base_url = "https://api.example.com/search"
search_params = {
    'q': 'Python 教程',
    'page': 1,
    'lang': 'zh-CN'
}
# 2. 对参数进行编码
encoded_query = urlencode(search_params, encoding='utf-8')
# 3. 将编码后的查询字符串拼接到基础URL上
# 使用 urlunparse 可以更安全地构建URL，它会把URL分解成6个部分
parsed_url = urlparse(base_url)
final_url = urlunparse((
    parsed_url.scheme,  # https
    parsed_url.netloc,  # api.example.com
    parsed_url.path,    # /search
    parsed_url.params,  # (通常为空)
    encoded_query,      # q=Python+%E6%95%99%E7%A8%8B&page=1&lang=zh-CN
    parsed_url.fragment # (通常为空)
))
print(f"最终构建的URL: {final_url}")
# 更简单的方式（如果URL没有复杂的部分）
# final_url_simple = f"{base_url}?{encoded_query}"
# print(f"简单方式URL: {final_url_simple}")

注意：在上面的输出中，"Python 教程" 被编码成了 Python+%E6%95%99%E7%A8%8B，空格被编码成了 号，这是查询字符串中的一个常见约定。urlencode 的默认行为就是这样。

常见问题与注意事项

为什么一定要指定 encoding='utf-8'？

如果不指定,Python 3 会使用 sys.getdefaultencoding()，这通常是 'utf-8'，但在某些特殊配置或旧代码环境中可能不是，显式指定 'utf-8' 可以确保代码在任何地方运行时行为一致，避免因环境不同导致的编码错误（比如乱码 或 ）。

quote vs urlencode vs quote_plus

• urllib.parse.quote(string): 用于编码 URL 的单个部分，比如路径、片段或单个参数值。

  from urllib.parse import quote
  path_segment = '用户/张三'
  encoded_path = quote(path_segment, encoding='utf-8')
  print(encoded_path) # 输出: %E7%94%A8%E6%88%B7/%E5%BC%A0%E4%B8%89

• urllib.parse.quote_plus(string): 类似 quote，但它还会将空格编码成 号，更适合编码查询字符串中的值。

  from urllib.parse import quote_plus
  query_value = 'Python 教程'
  encoded_value = quote_plus(query_value, encoding='utf-8')
  print(encoded_value) # 输出: Python+%E6%95%99%E7%A8%8B

• urllib.parseurlencode(seq/dict): 用于将一个完整的参数集合（字典或列表）转换成 key1=value1&key2=value2 格式的字符串，它在内部会调用 quote_plus 来处理每个值，当你有多个参数需要组合时，urlencode 是最方便的选择。

如何解码（urldecode）？

使用 urllib.parse.unquote() 函数。

from urllib.parse import unquote
encoded_string = "name=%E5%BC%A0%E4%B8%89&city=%E5%8C%97%E4%BA%AC"
# 解码
decoded_string = unquote(encoded_string, encoding='utf-8')
print(f"解码后的字符串: {decoded_string}")
# 输出: 解码后的字符串: name=张三&city=北京

在处理中文字符时,始终在编码和解码函数中明确指定 encoding='utf-8'，这是写出健壮、可移植代码的关键。