Python保存为CSV|专业指南与实战全解

掌握数据持久化的关键一步

备案号:蜀ICP备2026035467号-3 | 网址:www.xservx.com

一、为何需要掌握Python保存为CSV?

在数据驱动的时代,将处理后的数据持久化为通用格式,是数据分析师、工程师乃至科研人员的必备技能。CSV(Comma-Separated Values)虽结构简单,却因其跨平台、可读性强、兼容性广,成为数据交换的事实标准——从Excel、数据库到Hadoop生态,无不支持CSV。

尤其在以下场景中,Python保存为CSV能力直接影响工作效能:

值得注意的是,看似简单的`write_csv`操作,实则隐藏诸多坑点:中文乱码、浮点精度丢失、时间格式错乱、大文件内存溢出、编码声明缺失等——这些问题在生产环境中屡见不鲜,直接影响数据可信度与下游系统运行。

本文将从底层`csv`模块到高层`pandas`,系统梳理Python保存为CSV的全链路技术方案,并结合真实案例解析常见陷阱,助您构建可靠的数据持久化能力。

二、基础方案:使用内置csv模块保存

Python标准库自带`csv`模块,无需额外安装,适合轻量级场景。其核心优势在于可控性强、内存占用低,尤其适用于逐行流式写入。

2.1 最简示例

import csv
data = [
    ['姓名', '年龄', '城市'],
    ['张三', 28, '成都'],
    ['李四', 32, '西安'],
    ['王五', 24, '重庆']
]
with open('users.csv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(data)

关键点说明:

2.2 处理特殊字符与分隔符

CSV字段中若含逗号、换行符或双引号,需自动转义:

data = [
    ['备注', '内容'],
    ['含逗号', '苹果,香蕉,橙子'],
    ['含引号', '他说:"好的"'],
    ['含换行', '第一行\n第二行']
]
with open('special.csv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f, quoting=csv.QUOTE_ALL)
    writer.writerows(data)

`quoting=csv.QUOTE_ALL`确保所有字段用双引号包裹,自动转义内部引号(双引号转为`""`)。

2.3 自定义分隔符

某些场景需使用非逗号分隔符(如制表符、分号),通过`delimiter`参数实现:

with open('tab_separated.tsv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f, delimiter='\t')
    writer.writerow(['姓名', '工资'])
    writer.writerow(['赵六', 15000])

生成的TSV文件可在Excel中直接打开(文件→导入→分隔符号→制表符)。

三、高效方案:使用pandas.to_csv

`pandas`作为数据科学事实标准库,其`to_csv()`方法封装了大量实用参数,是Python保存为CSV的首选方案。

3.1 基础导出

import pandas as pd
df = pd.DataFrame({
    '姓名': ['张三', '李四', '王五'],
    '年龄': [28, 32, 24],
    '城市': ['成都', '西安', '重庆']
})
df.to_csv('pandas_users.csv', index=False, encoding='utf-8-sig')

关键参数:

3.2 精确控制数值精度

浮点数默认保留6位小数,易导致精度问题:

df = pd.DataFrame({
    '价格': [12.3456789, 99.0000001, 0.0000005]
})
df.to_csv('price.csv', index=False, float_format='%.2f')

生成CSV中价格为`12.35, 99.00, 0.00`,符合财务规范。

3.3 时间格式定制

时间列需指定格式,避免默认ISO格式(如`2024-05-20T14:30:00`):

df = pd.DataFrame({
    '订单号': ['A001', 'A002'],
    '下单时间': pd.to_datetime(['2024-05-20 14:30', '2024-05-21 09:15'])
})
df.to_csv('orders.csv', index=False, date_format='%Y年%m月%d日 %H:%M') 

输出为`2024年05月20日 14:30`,更符合中文阅读习惯。

3.4 处理缺失值

默认缺失值转为`NaN`,但业务系统可能需空字符串或特定标记:

df = pd.DataFrame({
    '姓名': ['张三', None, '王五'],
    '备注': [None, '已审核', '待处理']
})
df.to_csv('missing.csv', index=False, na_rep='(空)') 

缺失值显示为`(空)`,提升可读性。

四、编码问题深度解析

中文乱码是Python保存为CSV最常见问题,根源在于编码声明与读取方式不匹配。

4.1 核心原理

CSV文件本身不存储编码信息,需依赖外部约定:

4.2 正确编码选择策略

按使用场景选择:

推荐方案对比

场景推荐编码原因
Excel本地打开utf-8-sigBOM标识确保正确解码
网页下载后浏览器打开utf-8现代浏览器自动识别
数据库导入(如MySQL)utf8mb4避免字符集截断
旧系统兼容gb18030适配老版Office

4.3 实战验证

以下代码验证编码有效性:

import pandas as pd
import os
# 创建含中文的测试数据
df = pd.DataFrame({'测试列': ['测试中文', '中文测试']})
# 方案1:utf-8(Excel可能乱码)
df.to_csv('test_utf8.csv', index=False, encoding='utf-8')
print("文件大小(utf-8):", os.path.getsize('test_utf8.csv'))
# 方案2:utf-8-sig(推荐)
df.to_csv('test_utf8_sig.csv', index=False, encoding='utf-8-sig')
print("文件大小(utf-8-sig):", os.path.getsize('test_utf8_sig.csv'))
# 检查BOM存在(utf-8-sig应为3字节)
with open('test_utf8_sig.csv', 'rb') as f:
    bom = f.read(3)
    print("BOM字节:", bom.hex())  # 应输出: efbbbf

注意:`utf-8-sig`比`utf-8`多3字节BOM,但确保Excel兼容性。

五、大数据CSV写入优化

当数据量超内存时,需避免一次性加载全部数据。以下方案兼顾效率与稳定性。

5.1 流式分块写入

import pandas as pd
import csv
# 模拟100万行数据
def data_generator():
    for i in range(1_000_000):
        yield [i, f'名称_{i}', f'值_{i*0.5}']
# 分块写入CSV
chunk_size = 50_000
with open('large_data.csv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['ID', '名称', '值'])  # 写入表头
    chunk = []
    for row in data_generator():
        chunk.append(row)
        if len(chunk) >= chunk_size:
            writer.writerows(chunk)
            chunk.clear()
    if chunk:  # 写入剩余数据
        writer.writerows(chunk)
print("写入完成,文件大小:", os.path.getsize('large_data.csv') / 1024 / 1024, "MB")

5.2 pandas分块读写

结合`read_csv`与`to_csv`实现大数据转换:

import pandas as pd
output_file = 'converted.csv'
first_chunk = True
for chunk in pd.read_csv('big_input.csv', chunksize=100_000):
    # 数据处理(示例:新增列)
    chunk['新列'] = chunk['旧列'] * 2
    # 分块追加写入
    chunk.to_csv(output_file, mode='a', index=False,
                 encoding='utf-8-sig', header=first_chunk)
    first_chunk = False
print("转换完成!")

关键点:首次写入含表头(`header=True`),后续追加(`header=False`)。

5.3 性能对比测试

不同方案写入10万行数据耗时(秒)

方案单线程csv单线程pandas多进程pandas
内存占用低中高
写入时间2.83.11.9
适用场景小数据/简单结构中等数据/需处理大数据/多核环境

结论:小数据用`csv`模块;中等数据用`pandas`;超大数据需分块+多进程优化。

六、CSV与Excel互转技巧

尽管CSV轻量,但业务方常要求Excel格式。以下提供无依赖转换方案。

6.1 CSV转Excel(保留格式)

使用`openpyxl`保留原始格式(如数字、日期):

import pandas as pd
from openpyxl import load_workbook
# 读取CSV
df = pd.read_csv('data.csv', dtype=str)  # 全部读为字符串避免自动转换
# 写入Excel并设置格式
with pd.ExcelWriter('output.xlsx', engine='openpyxl') as writer:
    df.to_excel(writer, index=False, sheet_name='Sheet1')
    # 获取工作表
    ws = writer.sheets['Sheet1']
    # 自动列宽
    for idx, col in enumerate(df.columns):
        max_len = max(df[col].astype(str).map(len).max(), len(col)) + 2
        ws.column_dimensions[chr(65 + idx)].width = min(max_len, 50)

6.2 Excel转CSV(保留中文)

避免Excel自动转换日期/数字格式:

import pandas as pd
# 读取Excel时禁用类型推断
df = pd.read_excel('input.xlsx', dtype=str)
# 保存为CSV
df.to_csv('output.csv', index=False, encoding='utf-8-sig')

若需保留特定格式(如身份证号),可指定列类型:

df = pd.read_excel('input.xlsx', dtype={
    '身份证号': str,
    '手机号': str,
    '金额': float
})

七、从数据库导出CSV

数据库数据导出是Python保存为CSV高频场景,需注意字符集与分页。

7.1 MySQL导出方案

使用`pymysql`分页导出:

import pymysql
import csv
conn = pymysql.connect(
    host='localhost',
    user='root',
    password='password',
    database='testdb',
    charset='utf8mb4'
)
cursor = conn.cursor()
cursor.execute("SELECT COUNT(*) FROM users")
total = cursor.fetchone()[0]
chunk_size = 10000
with open('users_export.csv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f)
    for offset in range(0, total, chunk_size):
        cursor.execute(
            "SELECT * FROM users LIMIT %s OFFSET %s",
            (chunk_size, offset)
        )
        rows = cursor.fetchall()
        if offset == 0:
            # 写入列名
            writer.writerow([desc[0] for desc in cursor.description])
        writer.writerows(rows)
        print(f"已导出 {min(offset + chunk_size, total)} / {total} 行")
cursor.close()
conn.close()

7.2 PostgreSQL特殊处理

PostgreSQL默认用`UTF8`编码,但需确保客户端环境变量一致:

import os
os.environ['PGCLIENTENCODING'] = 'utf-8'  # 强制客户端编码
import psycopg2
# 后续连接操作...

否则可能因编码不一致导致乱码。

八、故障排查指南

整理高频问题及解决方案:

8.1 常见错误码与解决

错误速查表

错误现象可能原因解决方案
Excel打开乱码未加BOM或编码不匹配改用`utf-8-sig`
浮点数精度丢失`float`精度限制`float_format='%.10f'`
中文路径报错Windows路径编码用`r'路径'`或`os.path.join`
大文件打开卡顿Excel行数限制拆分为多个CSV(≤100万行/文件)
时间列变数字Excel自动识别序列号写入前转为字符串:`df['时间'].astype(str)`

8.2 调试技巧