本文介绍一种基于 python-docx 库中 contains_page_break 属性的可靠方法，通过识别段落级分页符来准确计算 Word 文档总页数，无需转换为 PDF 或依赖页脚/页码等易受干扰的元素。
本文介绍一种基于 `python-docx` 库中 `contains_page_break` 属性的可靠方法，通过识别段落级分页符来准确计算 word 文档总页数，无需转换为 pdf 或依赖页脚/页码等易受干扰的元素。
在 Python 中处理 .docx 文件时，常有需求需获取文档实际打印页数（如用于批量归档、合规检查或报告生成）。但需注意：python-docx 本身不直接提供“页数”属性——因为它是一个面向文档结构（而非渲染布局）的库，不模拟 Word 的排版引擎。因此，像“按字体大小、页边距、行高动态计算页数”这类操作在纯 python-docx 中不可行。
不过，一个被广泛忽略但高度实用的替代方案是：利用显式插入的分页符（Page Break）作为页面分隔的可靠标记。Word 用户或自动化流程常通过 Ctrl+Enter 或菜单插入硬分页符，这类分页符会被 python-docx 解析为段落（Paragraph）对象的 contains_page_break 属性（返回 True/False）。虽然该属性仅捕获 段落开头的分页符（即 \page 符号），但它在绝大多数业务场景中具备足够准确性——尤其当文档遵循规范排版（如每章起始页强制分页）时。
以下为推荐实现代码：
from docx import Document
def count_pages_by_pagebreaks(doc_path):
"""基于段落级分页符统计 Word 文档页数"""
doc = Document(doc_path)
# 每个 contains_page_break=True 的段落代表新页开始，因此页数 = 分页符数 + 1（首页）
page_break_count = sum(1 for p in doc.paragraphs if hasattr(p, 'contains_page_break') and p.contains_page_break)
return page_break_count + 1
# 使用示例
path = "report.docx"
total_pages = count_pages_by_pagebreaks(path)
print(f"文档共 {total_pages} 页")⚠️ 重要注意事项：
立即学习“Python免费学习笔记（深入）”；
- 此方法仅统计硬分页符（Manual Page Breaks），不识别由内容自动触发的“软分页”（如文本自然满页后换页）。若文档完全未插入任何分页符，则结果恒为 1；
- contains_page_break 是 python-docx >= 0.8.11 版本引入的属性，旧版本需升级：pip install --upgrade python-docx；
- 页脚中的页码（如“第 X 页”）无法被 python-docx 可靠提取为页数依据——因为页码是域字段（Field），其值在打开文档时才由 Word 引擎动态计算，python-docx 仅能读取原始域代码（如 PAGE），不能解析其运行时数值；
- 若需 100% 精确的渲染页数（含软分页），必须借助外部工具（如调用 Microsoft Word COM 接口、LibreOffice CLI 或专业 SDK），但这会牺牲跨平台性与部署简易性。
综上，对于结构清晰、含合理分页符的业务文档，sum(p.contains_page_break for p in doc.paragraphs) + 1 是当前 python-docx 生态中最简洁、稳定且零依赖的页数估算方案。
