docx2pdf 项目安装和配置指南

项目基础介绍

docx2pdf 是一个专业的文档转换工具，专门用于将 Microsoft Word 文档（.docx 格式）转换为 PDF 文件。该项目支持在 Windows 和 macOS 系统上直接使用 Microsoft Word 进行高质量的转换，确保转换后的 PDF 文件保持原始格式和布局。

主要编程语言：Python

关键技术框架

• Python: 项目核心编程语言，实现跨平台文档转换逻辑
• win32com: Windows 平台专用，通过 COM 接口与 Microsoft Word 交互
• JXA (JavaScript for Automation): macOS 平台专用，使用 AppleScript 的 JavaScript 实现与 Word 交互
• tqdm: 提供优雅的进度条显示，支持批处理进度跟踪
• CLI 接口: 提供命令行工具，支持单文件和批量转换

安装前准备工作

在安装 docx2pdf 之前，请确保满足以下系统要求：

1. Python 3.5+: 项目支持的 Python 版本
2. Microsoft Word: 必须安装 Microsoft Word 应用程序
3. pip: Python 包管理工具，通常随 Python 一起安装

详细安装步骤

方法一：使用 pip 安装（推荐）

pip install docx2pdf

方法二：使用 pipx 安装（隔离环境）

pipx install docx2pdf

方法三：macOS Homebrew 安装

brew install aljohri/-/docx2pdf

验证安装

安装完成后，可以通过以下命令验证安装是否成功：

docx2pdf --version

成功安装后会显示当前版本号（如：0.1.8）。

使用教程

单个文件转换

将单个 .docx 文件转换为 .pdf 文件，转换后的文件保存在原目录：

docx2pdf myfile.docx

批量文件夹转换

转换文件夹中的所有 .docx 文件：

docx2pdf myfolder/

指定输出路径

转换单个文件并指定输出文件名：

docx2pdf input.docx output.pdf

批量转换到指定文件夹

批量转换并将输出保存到指定文件夹：

docx2pdf input_dir/ output_dir/

Python 库使用方式

除了命令行工具，docx2pdf 还提供 Python API：

from docx2pdf import convert

# 单文件转换
convert("input.docx")

# 指定输出文件
convert("input.docx", "output.pdf")

# 批量文件夹转换
convert("my_docx_folder/")

Jupyter Notebook 支持

如果需要在 Jupyter Notebook 中使用 tqdm 进度条，需要额外安装：

pip install ipywidgets
jupyter nbextension enable --py widgetsnbextension

命令行选项说明

• input: 输入文件或文件夹路径
• output: 输出文件或文件夹路径（可选）
• --keep-active: 转换完成后不关闭 Word 应用程序
• --version: 显示版本信息
• -h, --help: 显示帮助信息

系统兼容性

• Windows: 支持所有 Windows 版本，需要安装 Microsoft Word
• macOS: 支持所有 macOS 版本，需要安装 Microsoft Word
• Linux: 不支持，因为需要 Microsoft Word 应用程序

项目结构说明

docx2pdf 项目包含以下核心文件：

• docx2pdf/__init__.py: 主要转换逻辑实现
• docx2pdf/convert.jxa: macOS 平台的 JXA 脚本
• pyproject.toml: 项目配置和依赖管理
• tests/: 单元测试目录

常见问题解决

1. 转换失败: 确保 Microsoft Word 已正确安装并可正常运行
2. 权限问题: 确保对输入输出目录有读写权限
3. 文件锁定: 确保要转换的 Word 文件未被其他程序占用

注意事项

• 转换过程需要 Microsoft Word 应用程序支持
• 大文件转换可能需要较长时间
• 批量转换时会显示进度条，方便跟踪转换进度
• 使用 --keep-active 选项可以避免频繁启动关闭 Word，提高批量转换效率

通过以上步骤，您可以成功安装和配置 docx2pdf 项目，开始高效地将 Word 文档转换为 PDF 格式。