# 你的 docx 替换为什么越改越乱：run 级编辑与合并单元格的两个坑

上个月我们接了个急活：一份 46 页的第三方检测咨询意见，要在交付前把甲方的单位名称统一换成新主体。听起来就是个"全文查找替换"的脚本活儿。结果交付当天甲方打回来：表格里那些黑边框怎么全没了？还有，合并单元格的"责任部门"那一栏，怎么出现了两份一模一样的内容？

这不是个例。凡是拿 python-docx 做过"按原文改几个字"的人，几乎都踩过这两条：要么格式被替换操作连锅端了，要么合并单元格被改了两遍。根子不在你代码写错了，而在 python-docx 暴露给我们的对象模型和 Word 底层 XML 之间的那层"善意封装"。本文把这两个坑一次讲透，并给两份能直接拷走跑通的源码。

环境说明：Python 3.8+，python-docx 1.1.2（文内代码在 0.8.11 及以上均可用，已在 1.1.2 实测）。下文所有 `w:` 前缀均指 OOXML 的 WordprocessingML 命名空间。

## 一、坑一：合并单元格被改了两遍，内容凭空翻倍

### 症状

你写了一段很朴素的遍历：

```python
for row in table.rows:
    for cell in row.cells:
        replace_text(cell, old, new)
```

跑完一看，凡是被纵向或横向合并过的单元格，"责任部门""检测结论"这类内容出现了两份、三份，甚至 N 份——N 等于这个合并区域覆盖的网格格子数。没合并的格子正常，偏偏合并的最离谱。

### 定位（成因）

这是 python-docx 对"合并单元格"的建模方式决定的。Word 里一个合并区域（比如纵向合并 3 行）在 XML 里其实只有一个 `<w:tc>`，其余 2 个格子是"被借走空间"的占位，靠 `gridSpan` / `vMerge` 属性声明"我这块儿归隔壁管"。但 python-docx 把表格当成一个 `行 × 列` 的规整矩阵来给你 `row.cells`，于是它为每个网格坐标都 new 一个 `_Cell` 包装对象指回同一个 `<w:tc>`。

关键就在这儿：**每次访问 `row.cells`，python-docx 都会重新构造 `_Cell` 包装器**，所以你拿到的"同一个合并格"在不同位置其实是不同的 Python 对象。你要是天真地用 `id(cell)` 去重，会发现自己去了个寂寞——因为 `id()` 作用在包装对象上，每次都是新 id，去重键永远不重复，于是合并格照样被命中多遍。

### 根治

去重必须落在**底层 XML 元素 `<w:tc>`** 上，而不是包装对象上。一行 `id(cell._tc)` 才是稳定的唯一键。正确写法：

```python
def iter_unique_cells(table):
    """遍历表格中的全部唯一单元格。
    合并单元格在 python-docx 中会生成多个包装对象，
    但它们的底层 <w:tc> 是同一个，故用 id(cell._tc) 去重。"""
    seen = set()
    for row in table.rows:
        for cell in row.cells:
            key = id(cell._tc)
            if key not in seen:
                seen.add(key)
                yield cell
```

使用时把"整表遍历"换成它，并在单元格内部走 run 级替换（见坑二）：

```python
for cell in iter_unique_cells(table):
    for para in cell.paragraphs:
        replace_in_runs(para, old, new)
```

这一改，合并区域只会被处理一次，内容翻倍彻底消失。后面坑二的函数正好接在这里用。

## 二、坑二：按全文替换，黑框和加粗全没了

### 症状

你图省事，直接：

```python
paragraph.text = paragraph.text.replace("旧名", "新名")
```

跑完字是换对了，但这一段的加粗、斜体、特殊字体全丢了。更隐蔽的是，某些段落替换后行距、缩进也跟着变——因为整段被"重置"了。很多人顺手还会写 `cell.text = cell.text.replace(...)`，结果单元格的黑色边框（视觉上那个框）也跟着没影了。

### 定位（成因）

`paragraph.text` 在 python-docx 里是一个 property 的 setter。给它赋值时，它会**把 `<w:p>` 下面所有 `<w:r>`（run）元素清空，再按你给的字符串重新造一个 run**。而加粗、字号、颜色这些信息都存在每个 run 的 `<w:rPr>`（run properties）里。整体重写 = run 全灭 = 格式全灭。

单元格黑边框定义在 `<w:tc>` 级的 `w:tcBorders` 上，本身不在段落里，被 `paragraph.text =` 单独改段落时不会被删。但现实里"黑框消失"几乎都是连带调用了整 cell 赋值（`cell.text =`）或重写了 cell 的 paragraphs，把 `<w:tc>` 的结构搅乱所致。一句话：**任何"整体赋值"式改写都是格式炸弹**。

### 根治

只动"文本"，不碰"格式"。办法是遍历 `paragraph.runs`，在每个 run 内部做 `str.replace`，`rPr` 原封不动留在元素上：

```python
def replace_in_runs(paragraph, old, new):
    """在 run 级替换文本，完整保留每个 run 的 rPr（字体/加粗/颜色等）。"""
    for run in paragraph.runs:
        if old in run.text:
            run.text = run.text.replace(old, new)
```

`run.text` 的 setter 只改这个 run 的 `<w:t>` 文本节点，不动 `<w:rPr>`。于是加粗还是加粗，黑框（在 cell 级）更不会被波及。把坑一的遍历和这个函数拼起来，就是一条"只改字、不破格式"的安全链路。

### 进阶：跨 run 的词语怎么办

`replace_in_runs` 有个前提：要换的词完整落在单个 run 内。但 Word 文档里一个词经常被拆到两个 run（比如前半段加粗、后半段没加粗，或中间插了个超链接）。这时 `old` 横跨 run 边界，`run.text` 里永远 match 不到，替换静静失败，你连报错都收不到。

彻底的解法是"重建 runs，但让新文本继承它所处位置的 rPr"：先把整段字符和每个字符归属的 run 索引记下来，做替换后，按 run 索引分段，用 `paragraph.add_run()` 重建，并把源 run 的 `<w:rPr>` 深拷贝过去。代码稍长，但它是跨 run 场景唯一能保住格式的办法：

```python
from copy import deepcopy
from docx.oxml.ns import qn

def replace_in_paragraph_preserve_format(paragraph, old, new):
    """跨 run 安全替换：重建 runs，新文本继承所在位置的 rPr。"""
    runs = paragraph.runs
    if not runs:
        return
    full_text = "".join(r.text for r in runs)
    if old not in full_text:
        return

    # 记录每个字符对应的源 run 索引，用于继承格式
    char_run_map = []
    for i, r in enumerate(runs):
        char_run_map.extend([i] * len(r.text))

    # 构造替换结果
    result_chars, result_run_idx = [], []
    i, L = 0, len(full_text)
    while i < L:
        if full_text.startswith(old, i):
            result_chars.append(new)
            result_run_idx.append(char_run_map[i])
            i += len(old)
        else:
            result_chars.append(full_text[i])
            result_run_idx.append(char_run_map[i])
            i += 1

    # 清空旧 runs
    p = paragraph._p
    for r in list(paragraph.runs):
        p.remove(r._element)

    # 按连续相同 run 索引合并重建，拷贝源 rPr
    prev_idx, cur_text = None, ""
    for ch, ridx in zip(result_chars, result_run_idx):
        if ridx == prev_idx:
            cur_text += ch
        else:
            if prev_idx is not None:
                _append_run(paragraph, cur_text, runs[prev_idx])
            prev_idx, cur_text = ridx, ch
    if cur_text:
        _append_run(paragraph, cur_text, runs[prev_idx])

def _append_run(paragraph, text, src_run):
    new_run = paragraph.add_run(text)
    src_rpr = src_run._element.find(qn("w:rPr"))
    if src_rpr is not None:
        new_run._element.append(deepcopy(src_rpr))
```

> 注意：跨 run 版本会按"字符所属的第一个 run"继承格式。如果一个词恰好跨在"加粗 run"和"普通 run"之间，替换后整块新文本会统一用前半段的格式——这是跨 run 替换无法回避的取舍，但总好过整体重写把格式全丢。

## 三、安全改写范式：四条铁律组合

把上面两个坑的解法收成一条可复用的"原地改写"范式，顺序不能乱：

1. **先建唯一映射**：遍历表格用 `iter_unique_cells`（按 `id(cell._tc)` 去重），保证合并格只进一次。
2. **run 级替换保 rPr**：正文与单元格内文本一律走 `replace_in_runs` / `replace_in_paragraph_preserve_format`，绝不碰 `paragraph.text =` 或 `cell.text =` 的整体赋值。
3. **黑边框 `w:tcBorders` 不动**：单元格边框在 `<w:tc>` 级，只要你不重写整个 cell、不调用会清空 paragraphs 的整 cell 操作，黑框天然保留。
4. **合并格先去重再改**：永远先 `iter_unique_cells` 再进替换逻辑，顺序颠倒就会回到"内容翻倍"。

一段完整调用示例：

```python
from docx import Document

def batch_replace(doc_path, old, new, out_path):
    doc = Document(doc_path)
    # 正文段落
    for para in doc.paragraphs:
        replace_in_paragraph_preserve_format(para, old, new)
    # 表格（唯一单元格 + cell 内段落）
    for table in doc.tables:
        for cell in iter_unique_cells(table):
            for para in cell.paragraphs:
                replace_in_paragraph_preserve_format(para, old, new)
    doc.save(out_path)

batch_replace("意见_初稿.docx", "旧主体名称", "新主体名称", "意见_终稿.docx")
```

## 四、踩坑实录：现象 + 成因 + 解法速查

下面把本文涉及的几个典型故障压缩成速查清单，照着对号入座即可。

**现象：合并单元格内容被复制成多份**
- 成因：python-docx 把合并区域当规整矩阵展开，`row.cells` 为每个网格 new 一个 `_Cell`，遍历会重复命中同一 `<w:tc>`。
- 解法：用 `iter_unique_cells` 按 `id(cell._tc)` 去重，合并格只处理一次。

**现象：用 `id(cell)` 去重没生效，内容依旧翻倍**
- 成因：`_Cell` 是每次访问现造的包装对象，`id(cell)` 每次都不同，根本没去成重。
- 解法：去重键必须落在底层元素 `cell._tc` 上，用 `id(cell._tc)`。

**现象：替换后加粗、字体、颜色全丢**
- 成因：`paragraph.text = ...` 是 property setter，会清空所有 `<w:r>` 再重建，run 的 `<w:rPr>` 随之消失。
- 解法：遍历 `paragraph.runs`，在 run 级 `run.text = run.text.replace(...)`，保留 rPr。

**现象：某个词死活替换不上**
- 成因：该词跨 run 边界被拆成两段，`run.text` 中无法整体匹配。
- 解法：用 `replace_in_paragraph_preserve_format` 重建 runs 并继承 rPr；或预处理时把该词所在段落格式统一。

**现象：单元格黑边框"消失"**
- 成因：调用了整 cell 赋值（如 `cell.text =`）或重写了 cell 的 paragraphs，搅乱了 `<w:tc>` 级的 `w:tcBorders`。
- 解法：只走 run 级替换，不碰整 cell 操作；边框在 cell 级，run 级改字天然不波及。

## 五、收尾

python-docx 的"友好封装"在帮你少写 XML 的同时，也把两个格式雷区藏在了默认行为里：合并单元格的重复命中，和 `paragraph.text` 整体赋值的格式清空。记住一句话就能避开九成事故——**改字只到 run 级，去重只认 `<w:tc>`**。把 `iter_unique_cells` 和 `replace_in_runs` / `replace_in_paragraph_preserve_format` 收进你的工具箱，下次"交付前改 46 份意见"这类活儿，跑完脚本直接交付，黑框还在，内容不多不少。


上个月我们接了个急活：一份 46 页的第三方检测咨询意见，要在交付前把甲方的单位名称统一换成新主体。听起来就是个"全文查找替换"的脚本活儿。结果交付当天甲方打回来：表格里那些黑边框怎么全没了？还有，合并单元格的"责任部门"那一栏，怎么出现了两份一模一样的内容？

你的 docx 替换为什么越改越乱：run 级编辑与合并单元格的两个坑

用 python-docx 批量改写 docx 时，为何黑边框消失、合并单元格内容翻倍？本文讲透 run 级编辑与合并单元格去重两个坑，给出 iter_unique_cells、replace_in_runs 等可运行源码，教你"只改字不破格式"的安全改写范式。

编程语言

开发工具

后端

python-docx替换格式混乱的根源：合并单元格被重复处理导致内容翻倍，以及段落整体赋值清空run格式。解决方案：用id(cell._tc)去重确保合并格只处理一次；通过run级替换保留rPr格式，配合跨run重建算法应对分词场景。提供完整可运行的批量替换代码，保障边框和样式不丢失。

代码解释

Python

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

你的 docx 替换为什么越改越乱：run 级编辑与合并单元格的两个坑-腾讯云开发者社区-腾讯云

你的 docx 替换为什么越改越乱：run 级编辑与合并单元格的两个坑

你的 docx 替换为什么越改越乱：run 级编辑与合并单元格的两个坑

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐