企业官网建设流程全解析

写文档自动化的时间长了，你会发现一个特别尴尬的现象：很多需求在 Word 里就是“点两下鼠标”的事，但一旦变成程序化任务，就完全不是那么回事了。比如“给文档加个背景色、背景图”，人工操作打开【设计】→【页面颜色】，十秒钟搞定；可要是放在批量生成标书、自动输出月度报告、给几百个模板统一换肤这种场景里，谁也不会去手点。

这篇文章就围绕“用 C# 设置 Word 文档的背景颜色和背景图”展开。我会直接从 docx 文件内部的存储结构说起，讲清楚背景色和背景图到底存在哪个 XML 里、图片是怎么挂上去的，再给出可复制的 OpenXML SDK 完整代码。整个过程不依赖本机安装 Word，Linux 容器上照样能跑，适合做报表自动化、模板定制、批量文档处理的人参考。

1. 先把底摸清楚：Word 的背景到底存放在哪儿

1.1 docx 就是一个压缩包，背景藏在 settings.xml 里

很多初学者一想到“操作 Word”，脑子里就默认要装 Office。实际上 docx 就是一个 zip 压缩包，里面是一组 XML 文件：正文在word/document.xml，样式在word/styles.xml，文档级设置在word/settings.xml，图片素材放在word/media/目录下。

关键知识来了：页面背景不属于正文内容，它被 Word 放在word/settings.xml里。一节和一段的底色可以写在正文里，但那种“每页都显示的整页背景色/背景图”，是文档级的设置。手动在 Word 里设置后，settings.xml 中会出现类似这样一段：

<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"> <w:displayBackgroundShape/> <w:background w:color="EEF3FF"/> </w:settings>

w:displayBackgroundShape是“显示背景形状”的开关，w:background元素带着 6 位十六进制颜色值。这两个元素经常一起出现，缺了前面那个开关，背景在 Word 的某些视图里就不会渲染。

1.2 背景图比背景色多了一层 VML

带背景图时，settings.xml 里的结构会复杂一些。Word 用了古老的 VML 语法来声明背景填充，实际内容长这样：

<w:background w:color="FFFFFF"> <w:drawing> <v:background id="_x0000_i1035"> <v:fill r:id="rId4" type="frame" recurse="false"/> </v:background> </w:drawing> </w:background>

v:fill里的r:id="rId4"是一个“关系 ID”，真正的图片地址在word/_rels/settings.xml.rels这个关系文件里，通过 Relationship 指向word/media/下的实际图片文件。这是 OOXML 里最核心的机制：XML 里不直接写文件路径，而是写一个关系 ID，再由关系文件做映射。改背景图的时候，只要把关系 ID 指向新加的图片部件就行。

type="frame"代表拉伸铺满整页，type="tile"代表平铺。后面讲到代码时会具体区分。

1.3 为什么不直接往正文里塞背景

群里经常有人问“我往 document.xml 里加一张全屏图片，不也能当背景吗”。能，但那是“贴纸”不是“壁纸”。正文里的浮动图片跟着段落走，翻页、编辑内容后位置会乱，还会被文本框、表格压在下面；而 settings.xml 里的背景是贴着页面的底层墙纸，每一页都稳定显示，和正文完全无关。理解这个区别，才能理解为什么代码要改的是 settings 而不是 document。

2. 三条实现路线，到底选哪条

2.1 三种方式的优缺点对比

COM 方案对很多人来说最眼熟，因为 Word 宏录出来的就是这套对象模型。但它的硬伤也很明显：服务器上必须装 Office，而且微软官方明确不建议在服务端跑 Office 自动化。一旦并发一多，WINWORD.EXE 进程会互相打架，客户看到的就是一堆僵尸进程和打不开的文件。

直接改 zip 是最朴素的办法：把 docx 后缀改成 zip，解压，动 XML，再压回去。好处是零依赖，坏处是容易漏步骤。最典型的是往包里新增了一张图片，却忘了在[Content_Types].xml里添加对应扩展名的 Default 声明，Word 打开时直接报“文档损坏”。这个方法我建议用来做“逆向学习”，而不是作为生产方案。

2.2 我的推荐：OpenXML SDK 为主力

OpenXML SDK 本质上是 OOXML 文档结构的强类型封装，它把 zip 解压、Content Types 维护、关系管理这些脏活都处理掉了。我用它主要是因为三点：不装 Office、能跨平台跑在 Linux 容器、批量处理时行为稳定。

唯一的代价是它并不提供“设置页面背景”这样的高级方法，等于说它给了你一把手术刀，病灶在哪得自己找。后面的代码就是在做这台手术。

2.3 准备工作与测试素材

先建一个控制台项目，装好 NuGet 包：

dotnet new console -n WordBackgroundDemo cd WordBackgroundDemo dotnet add package DocumentFormat.OpenXml

再准备三个测试素材：一个普通 docx 文件（最好带几段文字和一张正文图片）、一张准备当背景的 JPG/PNG 图片、以及一个能打开 docx 的解压工具。建议再装一个“Open XML SDK Productivity Tool”，它能直接查看任意 docx 的包结构和 XML，后面排查问题时比写代码方便得多。

3. C# 设置背景色：最简实现

3.1 核心代码

纯色背景是最常见的需求，代码也最干净。直接贴完整方法：

using DocumentFormat.OpenXml; using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Wordprocessing; static void SetSolidBackground(string docxPath, string hexColor) { using var doc = WordprocessingDocument.Open(docxPath, true); var settingsPart = doc.MainDocumentPart.DocumentSettingsPart; if (settingsPart == null) { settingsPart = doc.MainDocumentPart.AddNewPart<DocumentSettingsPart>(); } if (settingsPart.Settings == null) { settingsPart.Settings = new Settings(); } // 1. 写入背景色 var bg = settingsPart.Settings.GetFirstChild<Background>(); if (bg == null) { bg = new Background(); settingsPart.Settings.Append(bg); } bg.Color = hexColor; // 2. 确保显示开关存在 if (settingsPart.Settings.GetFirstChild<DisplayBackgroundShape>() == null) { settingsPart.Settings.Append(new DisplayBackgroundShape()); } settingsPart.Settings.Save(); }

调用方式很简单：SetSolidBackground(@"D:\test.docx", "EEF3FF")。执行完用 Word 打开，页面上应该就是浅蓝色背景了。

3.2 代码里每个步骤在干什么

WordprocessingDocument.Open(docxPath, true)的第二个参数是isEditable，必须传 true，否则保存时会报错。MainDocumentPart.DocumentSettingsPart拿到文档设置部件，这是一个“可选部件”，有些程序生成的 docx 里可能没有，所以要判空并新建。

Background和DisplayBackgroundShape是 OpenXML SDK 对 settings.xml 里对应元素的强类型封装。Background.Color属性映射的就是 XML 里的w:color属性。

这里有个需要注意的小地方：颜色值不能带#，也不能带透明度。w:color只接受 6 位十六进制 RRGGBB。写惯了 HTML 的人最容易在这翻车，传个#EEF3FF进去，Word 不一定报错，但颜色可能解析成黑色。

3.3 颜色格式与元素顺序的细节

如果你要用System.Drawing.Color转成 Word 颜色，可以写个小工具方法：

static string ToWordHex(Color c) { return ((c.R << 16) | (c.G << 8) | c.B).ToString("X6"); }

这里要手动把 alpha 通道丢掉，取 RGB 三通道拼成 24 位整数再转十六进制。

另一个细节是 settings.xml 里的元素顺序。严格按 ECMA-376 的 schema，displayBackgroundShape应该排在比较靠前的位置，background则在中后段。不过实测下来，Word 对顺序的容错度相当高，直接 Append 到末尾也能正常打开和显示。如果你有“强迫症”或者要做严格校验，可以在保存后用OpenXmlValidator检查一遍，再决定要不要用InsertBefore调整位置。

4. C# 设置背景图：难点全在 VML 填充

4.1 背景图的技术栈比想象中老

背景图之所以比背景色麻烦，是因为 Word 几十年来一直在用 VML 描述背景填充，而 OpenXML SDK 对 VML 的支持非常弱——它没有提供“背景图片”这种高级对象，连v:fill都没有现成的强类型封装。我试过用 SDK 的Vml.Fill类去拼，结果版本一换就编译不过。后来想通了：与其跟 SDK 搏斗，不如直接用原始 XML 字符串拼装，反而最稳定。

实现背景图的完整流程分三步：把图片文件作为ImagePart挂到 settings 部件下并拿到关系 ID；构造 VML 填充 XML；把 XML 写回w:background元素里。

4.2 完整代码

using DocumentFormat.OpenXml; using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Wordprocessing; static void SetImageBackground(string docxPath, string imagePath, bool tile = false) { using var doc = WordprocessingDocument.Open(docxPath, true); var settingsPart = doc.MainDocumentPart.DocumentSettingsPart; if (settingsPart == null) { settingsPart = doc.MainDocumentPart.AddNewPart<DocumentSettingsPart>(); } if (settingsPart.Settings == null) { settingsPart.Settings = new Settings(); } // 1. 把图片文件塞进包里，并拿到关系 ID // 不同 SDK 版本的 API 略有差别，如果你的版本里 SettingsPart 没有 AddImagePart， // 用 AddNewPart<ImagePart> 手动创建也可以，核心是拿到 rId。 string contentType = Path.GetExtension(imagePath).ToLower() switch { ".png" => "image/png", ".jpg" or ".jpeg" => "image/jpeg", ".gif" => "image/gif", _ => "image/jpeg" }; var imagePart = settingsPart.AddNewPart<ImagePart>(contentType, "bgImg"); using (var fs = File.OpenRead(imagePath)) { imagePart.FeedData(fs); } string relId = settingsPart.GetIdOfPart(imagePart); // 2. 构造 VML 填充 XML string fillType = tile ? "tile" : "frame"; string vml = $@" <w:drawing xmlns:w=""http://schemas.openxmlformats.org/wordprocessingml/2006/main"" xmlns:v=""urn:schemas-microsoft-com:vml"" xmlns:r=""http://schemas.openxmlformats.org/officeDocument/2006/relationships""> <v:background id=""bg{DateTime.Now.Ticks % 100000}""> <v:fill r:id=""{relId}"" type=""{fillType}"" recurse=""false""/> </v:background> </w:drawing>"; // 3. 把 XML 写回 background 元素 var bg = settingsPart.Settings.GetFirstChild<Background>(); if (bg == null) { bg = new Background(); settingsPart.Settings.Append(bg); } bg.Color = "FFFFFF"; bg.InnerXml = vml; if (settingsPart.Settings.GetFirstChild<DisplayBackgroundShape>() == null) { settingsPart.Settings.Append(new DisplayBackgroundShape()); } settingsPart.Settings.Save(); }

调用示例：SetImageBackground(@"D:\test.docx", @"D:\bg.png")。

4.3 展开讲讲图片和关系这块的机制

AddNewPart<ImagePart>(contentType, "bgImg")这行干了两件事：在包内新建一个图片部件，并在word/_rels/settings.xml.rels里生成一条指向它的 Relationship，同时把这个关系注册到[Content_Types].xml里。如果没有 SDK 帮你做这三件事，直接手工改 zip 极容易漏。

settingsPart.GetIdOfPart(imagePart)就是取刚才那条关系的 ID。在 VML 里写的r:id必须跟它一致，Word 才能顺着关系找到图片本体。这里有个非常典型的坑：如果你用了写死的rId，而当前文档里已经存在同名的关系 ID，OpenXML SDK 的AddNewPart会直接抛异常。所以上面代码里"bgImg"这个 ID 虽然是写死的，但实际项目里建议用"bg" + Guid.NewGuid().ToString("N")保证不会撞车。

4.4 背景图的平铺、拉伸和透明度控制

type="frame"是把图片拉伸到铺满整页，type="tile"是按原始尺寸平铺。实际使用中要注意三个问题。

第一，frame 拉伸会变形。A4 纸的纵横比大概是 297:210，约 1.414。如果你的背景图不是这个比例，拉伸后文字内容会被压扁或拉长——不对，严格说是背景图本身变形，但观感会非常明显，尤其是带 logo 或者边框纹理的图。解决方案有两个：要么把图片事先裁成 794×1123 像素（96dpi 下的 A4 尺寸）左右再用，要么就改用 tile 平铺小尺寸纹理，让重复拼接掩盖比例问题。

第二，低分辨率大图会糊。背景是整页渲染的，一张 200×200 的图被 frame 拉伸到全页，边缘锯齿会特别明显。在自动化流水线里，这一步最好在生成阶段就处理掉，而不是指望运行期缩放。

第三，透明度是 VML 的短板。VML 的v:fill虽然支持 opacity 之类的属性，但不同 Word 版本渲染结果差异很大，WPS 和 LibreOffice 的表现更不可控。我做半透明背景图时从来不在代码里做透明度，而是在出图阶段就把半透明效果烘焙进 PNG 里，这样所有平台看到的结果一致，省去大量兼容性调试。

5. 实战：批量生成带背景的文档

5.1 复制模板再逐个处理

真实项目里很少只处理一个文件，更常见的场景是“给一百个同模板 docx 批量加同样的背景”。这类需求我强烈建议用“先复制、后处理”的模式，绝不在原文件上直接写：

static void BatchAddBackground(string sourceDir, string targetDir, string imagePath, bool tile = false) { Directory.CreateDirectory(targetDir); foreach (var file in Directory.GetFiles(sourceDir, "*.docx")) { string target = Path.Combine(targetDir, Path.GetFileName(file)); File.Copy(file, target, true); SetImageBackground(target, imagePath, tile); } }

处理完任意捡几个文件手动打开验证，确认没有损坏或显示异常。这比写一百个单元测试都有效。

5.2 大文件批量处理的性能注意点

OpenXML SDK 打开文档时要把整个 zip 解压到内存，保存时再重新压缩。文件小感觉不到，一旦文档里嵌了大量图片、体积到了几十 MB，批量循环时会明显吃内存。

我的建议是：图片先读成byte[]再传入，避免每个文件都做磁盘 IO；处理完的文件先写到临时目录，全部成功后再 Move 到目标目录，防止中途失败留下一半坏文件；如果单文件特别大、数量特别多，可以考虑改用直接操作 zip 的方式，或者用OpenXmlPackage的流式接口，但这是另一个话题了。

5.3 打印和导出 PDF 时背景消失的问题

这是背景需求里最常见的“售后问题”。你先要把一个事实讲清楚：Word 默认不打印背景色和背景图。用户在屏幕上看得好好的，一导出 PDF 或打印，背景没了，立刻觉得你的程序有问题。

这个“打印背景”开关其实是 Word 界面的一个选项：文件 → 选项 → 显示 → “打印背景色和图像”。在 COM 里可以用app.Options.PrintBackground = true设置。但麻烦的是，OpenXML SDK 无法在文档文件里强制这个应用级选项，你生成的 docx 发给别人，人家 Word 没勾选就还是没背景。

如果你的客户硬性要求“导出 PDF 必须带背景”，我的经验是别用w:background这条路线，改成在每个节的页眉里放一张全尺寸衬底图片，或者放一个浮动的矩形形状。这样背景跟页面是一体的，打印和导出 PDF 都稳定保留，代价是实现复杂度高一些。做方案评估时，提前想清楚“背景到底要不要进 PDF”，这会直接影响技术选型。

6. 常见问题与排查实录

6.1 问题速查表

6.2 最实用的排查技巧：解压对比

我在排查这类问题时，最常用的方法不是查文档，也不是看代码，而是“用 Word 手动设置一次，保存后解压对比”。比如想知道 Word 自己生成的颜色和图片 XML 长什么样，就在空白文档里设置背景，然后用解压工具打开 settings.xml，直接抄它的写法。这一招比翻 OpenXML SDK 文档快得多，而且保证和当前 Word 版本完全兼容。

具体操作：复制一个 docx，改名 .zip，解压；用编辑器打开word/settings.xml，找到w:background；顺便看word/_rels/settings.xml.rels，确认图片关系；再对照你的代码生成的 XML，差异一目了然。这也是我第 1 节里那些 XML 片段最初的来源。

6.3 几个容易忽略的细节

处理已有背景的文档时，先判断w:background是否存在，存在就不要重复 Append，否则同一个元素出现两次，Word 虽然一般能容忍，但严格校验会报警。如果想彻底移除背景，把Background元素删掉即可；被遗弃的图片部件会留在包里变成垃圾数据，不影响打开，介意的可以连同关系一起删。

另外要记住，OpenXML SDK 只支持 OOXML 格式的 docx，不支持老的二进制 .doc。如果业务里混着 .doc 文件，得先用 Office 或第三方转换器转成 .docx 再处理，否则 SDK 打开时直接抛异常。

7. 写在最后：几个我踩出来的土经验

最开始做这个功能的时候，我直接拿着 OpenXML SDK 的文档从零拼 XML，结果怎么拼都报损坏。后来学乖了，先把 Word 手动设置的文档解压，把它的 settings.xml 原封不动抄下来再改，很快就通了。所以如果你刚上手，不妨也试试这个“先抄后改”的路线。

还有个经验是要把测试文件备份好。背景相关代码改的是整包结构，一旦出错文件可能就废了，反复从原始文件复制出来测，能少掉不少头发。颜色值不带#这事，我提醒了不知道多少次，群里照样有人踩；背景图比例不匹配这事，十个方案里有八个会忽略。把这两条写进团队的代码规约里，能省很多沟通成本。

最后说一句，w:background能做的其实不只是纯色和图片，VML fill 还能做渐变，type="gradient"加上color2属性就能实现从浅蓝到白的渐变背景。原理和背景图完全一样，只是v:fill的属性不同。有需要的话，照着本文的 XML 结构改几行就能扩展出来。文档自动化这东西，只要你理解了 docx 的包结构，后面再多需求都是水到渠成的事。