Go操作Word文档实战：github.com/nguyenthenguyen/docx

在自动化办公、批量生成文档、模板填充等场景中，经常需要程序化处理 Word 文件。如果你使用 Go 语言开发相关工具，一个非常实用的库是：

github.com/nguyenthenguyen/docx

这个库主要用于 基于模板替换内容生成 Word 文档，非常适合自动化生成合同、报告、通知书等文件。

一、docx 库是什么

github.com/nguyenthenguyen/docx 是一个用于处理 Word .docx 模板的 Go 库，作者是 Nguyen The Nguyen。

该库的核心功能是：

基于 Word 模板进行变量替换。

常见用途包括：

自动生成合同
批量生成报告
自动填充表单
批量生成通知书
证书生成系统

它的设计思路类似于：

Word 模板 + 占位符变量 + 程序替换。

二、docx 文件的本质

Word .docx 文件本质上是一个 ZIP 压缩包，内部包含 XML 文件。

主要结构：

arduino 复制代码

docx
 ├── word
 │    ├── document.xml
 │    ├── styles.xml
 │    └── media
 └── _rels

文档正文内容主要存储在：

arduino 复制代码

word/document.xml

docx 库通过解析 XML，然后替换占位符实现模板填充。

三、安装库

安装方法：

bash 复制代码

go get github.com/nguyenthenguyen/docx

导入库：

go 复制代码

import "github.com/nguyenthenguyen/docx"

四、创建 Word 模板

首先需要创建一个 Word 模板文件，例如：

arduino 复制代码

template.docx

在 Word 中写入内容：

复制代码

姓名：{name}
年龄：{age}
公司：{company}

这里的 {name}、{age}、{company} 就是占位符变量。

五、基本使用示例

下面是一个最基础的模板替换示例。

go 复制代码

package main

import (
	"log"

	"github.com/nguyenthenguyen/docx"
)

func main() {

	r, err := docx.ReadDocxFile("template.docx")
	if err != nil {
		log.Fatal(err)
	}
	defer r.Close()

	doc := r.Editable()

	doc.Replace("{name}", "张三", -1)
	doc.Replace("{age}", "28", -1)
	doc.Replace("{company}", "Tech Company", -1)

	err = doc.WriteToFile("output.docx")
	if err != nil {
		log.Fatal(err)
	}
}

执行后就会生成：

lua 复制代码

output.docx

内容将被替换为：

复制代码

姓名：张三
年龄：28
公司：Tech Company

六、Replace 参数说明

Replace 方法定义：

csharp 复制代码

Replace(old, new string, n int)

参数说明：

old 需要替换的占位符

new 替换后的内容

n 替换次数

示例：

diff 复制代码

-1

表示替换所有匹配内容。

七、批量生成 Word 文档

在实际应用中，经常需要批量生成文档。

例如批量生成合同。

示例：

go 复制代码

users := []map[string]string{
	{"name": "Alice", "age": "30"},
	{"name": "Bob", "age": "25"},
}

for _, u := range users {

	r, _ := docx.ReadDocxFile("template.docx")
	doc := r.Editable()

	doc.Replace("{name}", u["name"], -1)
	doc.Replace("{age}", u["age"], -1)

	doc.WriteToFile(u["name"] + ".docx")

	r.Close()
}

执行后会生成：

复制代码

Alice.docx
Bob.docx

八、模板设计建议

为了保证替换稳定，模板设计时需要注意：

1 占位符不要跨段落 2 占位符不要被 Word 自动拆分 3 建议使用简单格式

推荐占位符格式：

bash 复制代码

{name}
{date}
{price}

不推荐复杂结构。

九、常见问题

占位符替换失败

原因通常是 Word 自动拆分文本节点。

例如：

复制代码

{name}

可能被拆成多个 XML 节点。

解决方法：

重新输入占位符，确保在同一文本块中。

模板格式复杂

如果模板中包含：

表格
图片
复杂样式

有时会影响替换。

建议模板尽量保持结构简单。

不支持 .doc

该库只支持：

复制代码

.docx

旧版 Word .doc 不支持。

十、典型应用场景

docx 库适用于以下系统：

合同自动生成系统企业报告生成证书生成平台通知书批量生成发票或表单自动填充

例如：

输入用户数据

复制代码

姓名
身份证
公司
职位

系统自动生成 Word 文档。

十一、与其他方案对比

方案	特点
docx	简单模板替换
unioffice	功能强但较复杂
COM 自动化	需要安装 Word
Python-docx	Python 方案

如果只需要 模板替换生成文档，docx 是非常轻量的选择。

十二、总结

github.com/nguyenthenguyen/docx 是一个简单高效的 Word 模板处理库。

主要特点：

使用 Word 模板
占位符替换
API 简单
适合批量文档生成

对于需要自动生成 Word 文件的 Go 项目来说，这个库可以大幅简化开发流程。

通过结合数据库和模板系统，可以快速构建：

自动化文档生成平台。