CSV 转 Excel 转换器

概述

本技能支持将 CSV 文件转换为 Excel 格式，具备专业级格式化能力、对中文字符的正确编码处理，以及将多个 CSV 文件合并为一个 Excel 工作簿（每个 CSV 对应一个独立工作表）的功能。

快速开始

所有转换操作均使用 csv_to_excel.py 脚本：

# 单个 CSV 转 Excel
python scripts/csv_to_excel.py input.csv output.xlsx

# 多个 CSV 合并为一个 Excel（每个 CSV 作为独立工作表）
python scripts/csv_to_excel.py file1.csv file2.csv file3.csv --output combined.xlsx

# 指定自定义工作表名称
python scripts/csv_to_excel.py sales.csv inventory.csv --output report.xlsx --sheet-names "销售数据" "库存数据"

功能特性

自动编码检测

• 自动识别 CSV 编码（UTF-8、GBK、GB2312、UTF-8-SIG）
• 确保中文字符在 Excel 中正确显示
• 无需手动指定编码

专业级格式化

• 表头行：蓝色背景 + 白色粗体文字
• 边框：所有单元格外围添加细边框
• 列宽：根据内容自动调整（对中文字符适配良好）
• 冻结窗格：冻结表头行，便于滚动查看数据
• 对齐方式：表头文字居中对齐

多工作表支持

• 支持将多个 CSV 文件合并至单个 Excel 工作簿
• 每个 CSV 文件生成一个独立工作表
• 支持自定义工作表名称
• 默认工作表名称为 CSV 文件名（最长 31 个字符）

常见使用模式

模式 1：单文件转换

用户输入：“将 data.csv 转为 Excel”

python scripts/csv_to_excel.py data.csv data.xlsx

模式 2：多文件合并为多工作表 Excel

用户输入：“将这些 CSV 文件合并为一个 Excel，每个文件作为一个独立工作表”

python scripts/csv_to_excel.py sales_2024.csv sales_2025.csv inventory.csv --output report.xlsx

结果：report.xlsx 包含 3 个工作表，名称分别为 “sales_2024”、“sales_2025” 和 “inventory”

模式 3：自定义工作表名称

用户输入：“用这些 CSV 创建 Excel，并以中文命名工作表”

python scripts/csv_to_excel.py q1.csv q2.csv q3.csv q4.csv --output 年度报告.xlsx --sheet-names "第一季度" "第二季度" "第三季度" "第四季度"

模式 4：处理含中文内容的 CSV

用户输入：“这个 CSV 包含中文文本，在 Excel 中显示为乱码”

该脚本会自动检测编码并正确处理中文字符：

python scripts/csv_to_excel.py 中文数据.csv 输出.xlsx

技术细节

编码支持

脚本按以下顺序尝试识别编码：

1. UTF-8
2. GBK（中文 Windows 常用）
3. GB2312（简体中文）
4. UTF-8-SIG（带 BOM 的 UTF-8）
5. Latin1（兜底方案）

CSV 格式自动识别

• 自动识别分隔符（逗号、分号、制表符等）
• 支持带引号的字段
• 兼容多种 CSV 格式

列宽计算规则

• 中文字符计为 2 个宽度单位
• ASCII 字符计为 1 个宽度单位
• 最大列宽限制为 50（保障可读性）
• 额外增加 2 个单位的视觉留白

依赖项

脚本依赖 openpyxl 库：

pip install openpyxl

故障排查

问题：中文字符仍显示为乱码

• 解决方法：CSV 文件可能采用非常规编码。建议先使用文本编辑器将其转为 UTF-8 编码后再运行脚本。

问题：工作表名称报错

• 解决方法：Excel 工作表名称长度不得超过 31 个字符。脚本会自动截断超长名称；您也可主动指定更短的自定义名称。

问题：生成了空工作表

• 解决方法：请检查 CSV 文件是否为空，以及其格式是否符合标准。

问题：脚本未找到

• 解决方法：请在技能根目录下运行该脚本，或使用完整路径：python .kiro/skills/csv-to-excel/scripts/csv_to_excel.py