使用python-docx替换标准化报告占位符部分失效问题求助

我想用python-docx把项目报告改成模板，自动替换里面的占位符，但首页的占位符怎么都替换不了，其他页面的正常。试过改占位符格式（删空格、换连字符），甚至重建文档逐页处理，都没解决。

相关素材 #

• 问题模板截图
• 运行结果截图
• 相关文件文件夹
• 替换值列表截图

我使用的代码 #

from docx import Document
import pandas as pd
import os

def load_data(file_path):
    """Load data from CSV file."""
    try:
        df = pd.read_csv(file_path)
        
        # Use first two columns regardless of names
        if len(df.columns) >= 2:
            first_col, second_col = df.columns[0], df.columns[1]
            
            # Clean up the data
            df[first_col] = df[first_col].astype(str).str.strip()
            df[second_col] = df[second_col].fillna("").astype(str).str.strip()
            
            return dict(zip(df[first_col], df[second_col]))
        else:
            raise ValueError("CSV file must have at least 2 columns")
            
    except Exception as e:
        print(f"Error reading CSV file: {file_path}")
        print(f"Error details: {str(e)}")
        raise

def replace_placeholders(doc, data):
    """Replace placeholders in document with values from data."""
    for paragraph in doc.paragraphs:
        for run in paragraph.runs:
            for key, value in data.items():
                placeholder = f"<<{key}>>"
                if placeholder in run.text:
                    run.text = run.text.replace(placeholder, str(value))

def generate_report(template_path, output_path, data_path):
    """Generate report from template using data."""
    try:
        # Remove existing output file if it exists
        if os.path.exists(output_path):
            os.remove(output_path)
            print(f"Removed existing output file: {output_path}")
        
        # Load data and create report
        data = load_data(data_path)
        print(f"Loaded {len(data)} replacements from CSV")
        
        doc = Document(template_path)
        replace_placeholders(doc, data)
        doc.save(output_path)
        print(f"Report generated: {output_path}")
        
    except Exception as e:
        print(f"Error generating report: {str(e)}")
        raise

# File paths
template_path = r"C:\xxxxx\Test4.docx"
output_path = r"C:\xxxxx\generated_acquisition_report.docx"
data_path = r"C:\xxxxx\data2.csv"  # Changed to .csv

if __name__ == "__main__":
    generate_report(template_path, output_path, data_path)

解决思路和修复方案 #

1. 解决文本拆分导致的匹配失败

Word会把同一段落的文本拆分成多个run（比如因格式变化、隐藏格式），导致<<占位符>>被拆成多段（比如<<在一个run，占位符在另一个，>>在第三个），你的代码就匹配不到。

快速修复（牺牲部分格式）：直接按段落整体替换，代码更简洁：

def replace_placeholders(doc, data):
    """Replace placeholders in document with values from data."""
    for paragraph in doc.paragraphs:
        full_text = paragraph.text
        # 批量替换所有占位符
        for key, value in data.items():
            placeholder = f"<<{key}>>"
            full_text = full_text.replace(placeholder, str(value))
        # 替换整个段落文本
        paragraph.text = full_text

保留格式的修复：逐run拼接文本检查完整占位符，适合需要保留原格式的场景：

def replace_placeholders(doc, data):
    """Replace placeholders while preserving formatting."""
    for paragraph in doc.paragraphs:
        runs = paragraph.runs
        i = 0
        while i < len(runs):
            current_text = runs[i].text
            j = i + 1
            # 往后拼接run文本，直到找到完整占位符或段落末尾
            while j < len(runs):
                current_text += runs[j].text
                # 检查当前拼接文本是否包含占位符
                match_found = False
                for key, value in data.items():
                    placeholder = f"<<{key}>>"
                    if placeholder in current_text:
                        # 替换占位符
                        new_text = current_text.replace(placeholder, str(value))
                        runs[i].text = new_text
                        # 删除多余的run
                        for k in range(j-1, i, -1):
                            del runs[k]
                        match_found = True
                        break
                if match_found:
                    break
                j += 1
            i += 1

2. 检查页眉/页脚的占位符

如果首页占位符在页眉或页脚里，原代码没处理这些区域，需要补充：

def replace_placeholders(doc, data):
    """Replace placeholders in body, headers and footers."""
    # 处理正文
    for paragraph in doc.paragraphs:
        full_text = paragraph.text
        for key, value in data.items():
            placeholder = f"<<{key}>>"
            full_text = full_text.replace(placeholder, str(value))
        paragraph.text = full_text
    
    # 处理页眉
    for section in doc.sections:
        for header in section.headers:
            for paragraph in header.paragraphs:
                full_text = paragraph.text
                for key, value in data.items():
                    placeholder = f"<<{key}>>"
                    full_text = full_text.replace(placeholder, str(value))
                paragraph.text = full_text
    
    # 处理页脚
    for section in doc.sections:
        for footer in section.footers:
            for paragraph in footer.paragraphs:
                full_text = paragraph.text
                for key, value in data.items():
                    placeholder = f"<<{key}>>"
                    full_text = full_text.replace(placeholder, str(value))
                paragraph.text = full_text

3. 验证占位符的一致性

确认CSV里的占位符名称（不带<<>>）和模板里的完全一致，检查是否存在大小写差异、全角/半角空格、隐藏字符等问题，可直接复制CSV内容到模板测试。

内容的提问来源于stack exchange，提问作者Cate Ellie