禅道Bug导出CSV文件批量转Word离线部署操作手册
文档版本：V1.0
适配环境：Windows 10/11 64 位、Miniconda3-py310_23.10.0-1（Python3.10）
完全离线无外网适用工具：禅道导出 CSV 文件、Python 转换脚本、离线 whl 依赖包、批处理一键启动脚本
文件路径基准：E:\Bugtool\Csvbugtoword
一、离线工具整体打包目录规范
1. 总打包根目录命名：Csvbugtoword
Csvbugtoword
├─ Miniconda3-py310_23.10.0-1-Windows-x86_64.exe
├─ downloaded_images （截图本地缓存文件夹）
├─ out_word （最终Word输出文件夹）
├─ whl （Python全量离线依赖包）
├─ BugtoWord.bat （一键启动批处理脚本）
├─ export_bugs_to_word.py （正式转换主脚本）
└─ 智能家居-Bug (2).csv （禅道导出原始Bug表格文件）
└─ 禅道Bug导出CSV文件批量转Word离线部署操作手册.docx
2. 打包硬性要求
- downloaded_images、out_word、whl 三个文件夹名称不改名、不动层级；
- whl 内所有依赖包必须为 cp310-win_amd64 版本，包含：requests、beautifulsoup4、python-docx、Pillow、lxml、typing-extensions，版本不可混用。
二、离线电脑分步部署操作流程
步骤 1：离线安装 Miniconda Python 环境（所有新电脑必装）
- 打开【Csvbugtoword】文件夹，双击Miniconda3-py310_23.10.0-1-Windows-x86_64.exe；
- 安装弹窗操作步骤：
- I Agree 同意许可协议；
- 安装类型选择：Just Me (recommended) 仅当前用户安装；
- 安装路径默认填写：C:\Users\Administrator\miniconda3，建议默认；
路径如果修改，若用户 Miniconda 自定义安装到 D 盘 / 其他路径，只需要修改激活行路径，D:\miniconda3\Scripts\activate.bat 2>nul
- 高级选项配置：
✅ 勾选：Register Miniconda3 as my default Python 3.10
❌ 取消勾选：Add Miniconda3 to my PATH environment variable禁止添加进系统环境变量，避免多 Python 版本冲突；
- 点击 Install 等待进度跑完，点击 Finish 结束，不要打开 conda 终端。
步骤 2：部署业务文件夹 Csvbugtoword
- 将完整 Csvbugtoword 文件夹，整体复制到电脑 E 盘 Bugtool 文件夹下，最终路径：E:\Bugtool\Csvbugtoword；
- 核对目录必备文件：
1）根目录存在 CSV 文件、BugtoWord.bat、export_bugs_to_word.py；
2）whl 文件夹所有离线依赖包齐全；
- 双击文件夹内 BugtoWord.bat 自动运行（建议右键 BugtoWord.bat，选择以管理员身份运行，规避 Windows 拦截），流程自动执行：环境校验→离线安装依赖→运行转换脚本。
步骤 3：【重点】日常使用转换操作
- 登录禅道后台，打开 Bug 列表，导出文件格式选择 CSV，导出后复制到Csvbugtoword文件夹，删除原始csv文件；
- 在Csvbugtoword文件夹，打开export_bugs_to_word.py文件更新cookie（执行的时候禅道退出登录或者超时就需要更新cookie）；
- 进入E:\Bugtool\Csvbugtoword 文件夹，cmd；
- 执行命令python export_bugs_to_word.py；
- 运行结束，进入 out_word 文件夹，打开生成 Word 文档，所有 Bug 信息、截图全部内嵌；
- 每次更新禅道 Bug 数据，重复替换 CSV、更新cookie，进入文件路径cmd执行命令python export_bugs_to_word.py即可。
三、重点注意：如果本地安装了其他版本的python安装包，执行会报错，需要执行如下操作
- Windows 开始菜单内的快捷入口：Anaconda Prompt (miniconda3)
也就是 Miniconda 专属终端，是本次禅道 CSV 转 Word 离线工具的配套命令行环境
2、手动离线安装依赖（备用方案）
若 Bat 脚本运行异常，可打开此终端，进入E:\Bugtool\Csvbugtoword目录，执行离线安装命令：
cd /d E:\Bugtool\Csvbugtoword
pip install --no-index --find-links=./whl requests beautifulsoup4 python-docx Pillow lxml typing-extensions
3、手动运行 Python 转换脚本
python export_bugs_to_word.py
- 禅道如果更新IP，需要替换export_bugs_to_word.py中的全部IP
四、重要约束与注意事项
- 脚本拉取禅道截图依赖账号 Cookie，Cookie 过期后图片无法下载，文字正常导出；解决：登录禅道浏览器复制最新 Cookie，填写到 Python 脚本对应参数位置；
- 离线电脑必须内网可访问禅道服务器 IP，内网不通，截图无法加载。
五、常见故障排查对照表
表格
|----------------------|--------------------------------|--------------------------------------|
| 故障现象 | 故障原因 | 处理方案 |
| 提示 python/pip 不是内部命令 | Miniconda 安装路径错误、bat 未激活 conda | 重装 Miniconda 到指定 C 盘路径，使用本文完整 bat 脚本 |
| Word 只有文字无截图 | Cookie 失效、内网无法连通禅道 | 更新脚本内禅道 Cookie；检查内网能否 ping 通禅道地址 |
| 脚本找不到 CSV 文件 | CSV 放错文件夹 | CSV 必须放在 Csvbugtoword 根目录 |
六、多电脑迁移方案
- 随身携带：Miniconda 安装程序 + 完整 Csvbugtoword 文件夹；
- 新电脑操作：先安装固定路径 Miniconda，再将 Csvbugtoword 复制到目标电脑 E:\Bugtool；
- 所有文件夹结构、名称全程保持原样，不做修改。
七、日常运维建议
- 定期全量备份 Csvbugtoword 文件夹，保存 whl 包、Python 脚本、有效 Cookie；
- 禅道更新了ip地址，export_bugs_to_word.py文件中的IP统计替换即可；
- 禅道账号更换、密码修改，必须同步更新脚本 Cookie；
- downloaded_images 可定期清空，清理缓存节省硬盘空间，不影响 Word 文件。