Python Word插入超链接：外链和邮箱链接
用python-docx在Word文档里插入可点击的超链接，包括网页链接和mailto邮箱链接，支持设置颜色和下划线，批量给报告目录、参考资料加链接。
场景痛点
写报告要引用一堆参考资料，手动"插入-链接"一个个粘贴URL，几十条下来鼠标都点坏。而且python-docx没有现成的 add_hyperlink 方法，需要手工加XML关系。封装好函数后，批量在文档里加外链、邮箱链接、内部书签链接都很方便。
用到的库
pip install python-docx
完整代码
# -*- coding: utf-8 -*-
"""
在 Word 文档里插入超链接（网页 / 邮箱 / 内部书签）
"""
from pathlib import Path
from docx import Document
from docx.oxml.ns import qn
from docx.oxml import OxmlElement
from docx.opc.constants import RELATIONSHIP_TYPE as RT
def add_hyperlink(paragraph, url, text, color="0563C1", underline=True):
"""
在段落末尾追加一个超链接
:param url: 链接地址，如 https://example.com 或 mailto:hi@example.com
:param text: 显示文字
:param color: 颜色RGB，默认 Word 链接蓝
:param underline: 是否下划线
"""
part = paragraph.part
# 在文档关系里新增一个外部链接关系
r_id = part.relate_to(
url,
RT.HYPERLINK,
is_external=True,
)
# 构造 w:hyperlink 元素
hyperlink = OxmlElement('w:hyperlink')
hyperlink.set(qn('r:id'), r_id)
# 构造 run
new_run = OxmlElement('w:r')
rPr = OxmlElement('w:rPr')
# 颜色
c = OxmlElement('w:color')
c.set(qn('w:val'), color)
rPr.append(c)
# 下划线
if underline:
u = OxmlElement('w:u')
u.set(qn('w:val'), 'single')
rPr.append(u)
new_run.append(rPr)
# 文字
t = OxmlElement('w:t')
t.text = text
t.set(qn('xml:space'), 'preserve')
new_run.append(t)
hyperlink.append(new_run)
paragraph._p.append(hyperlink)
return hyperlink
def demo():
doc = Document()
doc.add_heading("参考资料", level=1)
# 普通网页链接
p1 = doc.add_paragraph()
p1.add_run("[1] 官方文档：")
add_hyperlink(p1, "https://python-docx.readthedocs.io/", "python-docx 官方文档")
# 邮箱链接
p2 = doc.add_paragraph()
p2.add_run("[2] 联系作者：")
add_hyperlink(p2, "mailto:contact@example.com", "contact@example.com")
# 加在已有段落里
p3 = doc.add_paragraph("更多内容请访问 ")
add_hyperlink(p3, "https://www.example.com", "公司官网", color="C00000")
p3.add_run(" 了解详情。")
out = Path("./hyperlink_demo.docx")
doc.save(str(out))
print(f"已生成：{out}")
print("打开后 Ctrl+点击 链接可跳转。")
if __name__ == "__main__":
demo()
代码讲解
python-docx 把超链接当作一个关系（relationship）存在文档包里。add_hyperlink() 先调 part.relate_to(url, RT.HYPERLINK, is_external=True) 让Word把URL存成外部关系，拿到一个关系ID r_id。
然后手工拼 w:hyperlink 元素，r:id 属性指向那个关系ID。里面的run设置颜色（默认 0563C1 就是Word默认链接蓝）和下划线，文字用 w:t 包起来。最后把这个hyperlink元素append到段落的XML里。
mailto: 开头的URL就是邮箱链接，点击会唤起邮件客户端。想改颜色传 color="C00000"（红色）就行。
运行结果
打开 hyperlink_demo.docx，"python-docx 官方文档""contact@example.com""公司官网"都是蓝色带下划线的链接，按住Ctrl点击可跳转。邮箱链接点击会弹出邮件客户端。
注意事项
- 链接是"外部关系"，复制文档到别的电脑链接仍然有效（因为URL写在文档里）。
- 想做"内部跳转书签"链接，
is_external=False，url写成#书签名称，需要先用doc.add_bookmark()之类的方式加书签。 - 颜色用的是Word十六进制RGB（不带#），不是CSS格式。
- 转PDF时LibreOffice和Word都会把链接保留成可点击的，除非你关掉PDF导出选项里的"转换文档链接"。
- 批量给目录加链接时，注意URL里的中文和特殊字符要URL编码（urllib.parse.quote），否则Word可能识别不了。
更新时间：2026-09-15 08:57:32