Java读取Word并上传数据库：解析、存储与避坑指南

简介：面向需要实现 Word 文档内容自动入库的 Java 开发者，资源围绕 Apache POI 解析 Word 与 JDBC 批量写入数据库展开，覆盖 XWPFDocument 读取文本和表格、数据转换、PreparedStatement 防注入及事务处理等关键环节，适合有一定 Java 基础并希望提升数据录入效率的读者。压缩包共 41 个文件，约 13.24MB，包含 9 个 Java 源码、9 个编译后的 class、11 个依赖 jar 包，以及 XML 配置、数据库 properties 配置和 Eclipse 工程文件，WebContent 目录还提供可直接部署的 Web 工程结构，便于导入项目后同步调试。目前已有 5138 人学习下载。通过研究示例代码可掌握 POI 解析 .docx 的完整流程、表格式数据的提取与转换思路，结合配置文件和目录结构还能理解 Web 项目中如何整合文件上传、解析入库与异常处理；从源码、class 到构建配置的完整目录，也有助于对照学习依赖管理与打包发布，是一份兼顾入门示范与工程参考的实用素材。

1. 读取 Word 并上传数据库：先想清楚你存的是什么

很多刚接触这个需求的人，第一反应是「用 POI 把 Word 解析成字符串，然后 INSERT 进数据库」。但真正落过地的人都知道，这个标题背后其实藏着两条完全不同的技术路线：一条是把 Word 文件本身以二进制形式存进数据库，另一条是把 Word 里的文字内容解析出来存成文本。这两条路对库表设计、代码结构、甚至中间件选型的影响天差地别。如果动手前没想清楚，十有八九会在做完之后发现「能跑，但根本没法用」——比如文件能传上去却打不开，或者内容提取出来全是乱码和丢失的格式。

这篇文章会从 Java 读取 Word 的库选型讲起，把 .doc 和 .docx 的区别、文本与图片的抽取方式、数据库字段怎么设计、二进制和文本两条存储路线各自的实现代码全部拆开，最后列几个我实际踩过的坑。适合正在做文件管理系统、内容审核系统、OA 公文归档这类功能的开发者，也适合被「Word 转存数据库」需求卡住、不知道该从哪下手的应届生。读完你就能照着写出一套能跑的方案，并且知道每条代码背后的参数为什么这样设。

2. 解析库选型和 Word 版本差异：为什么不是所有库都通吃

2.1 POI 与 docx4j 的边界：选库前先分清三种场景

Java 处理 Word 的库主要就两个方向：Apache POI 和 docx4j。很多教程喜欢说「用 POI 就行」，但实际项目里选哪个，取决于你要对 Word 做什么。

如果你的需求是「读取 Word 全文内容，提取文字丢进数据库做检索或展示」，Apache POI 是首选。POI 的 XWPF 组件专门处理 .docx，HWPF 处理老式 .doc 文件。它对文本抽取的支持最成熟，内存占用相对可控，而且社区资料多、遇到问题容易搜到解决方案。另一个常见选择是 docx4j，它在处理 .docx 的 XML 结构时更贴近 OOXML 规范，适合做复杂的格式转换，比如 Word 转 PDF、Word 转 HTML，但单纯取文本的话反而显得重。

还有一类场景是只读不解析，比如用户上传的是 .doc 老文件，公司又不愿意引入太多依赖，那可以考虑用 Apache Tika。Tika 本身也是基于 POI 做底层解析的，但接口更「傻瓜化」，一段文字进去一段文字出来，省掉很多 POI 的样板代码。不过 Tika 对表格和图片的精细控制不如直接操作 POI，适合「只要正文不要结构」的场景。

回到标题「java实现读取word文件并且上传到数据库」，我一般会先问一句：你后续要对这些内容做什么？如果只是把文件收进库里存档，那就别费劲解析文本了，直接存二进制文件最简单；如果还要做内容检索、敏感词过滤、在线预览，那文本抽取才是正路。这两种需求对应的代码，后面会分别给出实现。

2.2 .doc 与 .docx 的本质差异：一个 API 搞不定所有老文件

这条坑很多人都是上线之后才发现的：用户传了个 .doc 老文件，程序直接报错。原因在于 .doc 是二进制复合文档格式（CFB），.docx 是 ZIP 压缩的 XML 格式，两者结构完全不同，POI 的处理入口也不一样。

代码里最常见的错误是拿 XWPFDocument 去加载 .doc 文件，构造器一执行就抛异常。正确做法是先按文件名后缀或文件的魔数来判断格式，再分别走 XWPFDocument（.docx）和 HWPFDocument（.doc）两套逻辑。

import org.apache.poi.hwpf.HWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFDocument; // 根据文件扩展名路由到不同的解析器 public String extractText(byte[] fileBytes, String fileName) throws Exception { if (fileName.toLowerCase().endsWith(".docx")) { // XWPF 解析的是 OOXML 格式，对应 Office 2007 以后的 .docx try (XWPFDocument doc = new XWPFDocument(new ByteArrayInputStream(fileBytes))) { return parseDocx(doc); } } else if (fileName.toLowerCase().endsWith(".doc")) { // HWPF 解析的是 OLE2 复合文档，对应 Office 2003 及以前的 .doc try (HWPFDocument doc = new HWPFDocument(new ByteArrayInputStream(fileBytes))) { return parseDoc(doc); } } else { throw new IllegalArgumentException("不支持的文件类型: " + fileName); } }

这段代码的关键在于分路由，因为 XWPFDocument 和 HWPFDocument 的解析逻辑完全不一样。parseDocx 内部通常遍历段落 XWPFParagraph 和表格 XWPFTable，parseDoc 则直接用 WordExtractor 抽取纯文本。如果你的系统只允许上传 .docx，那可以省略 HWPF 分支，但现实中大部分管理系统都免不了老文件入湖，建议从第一天就做好双分支支持。

文件类型判断还有一个细节：不要只信文件后缀名。某些系统导出的「伪 .doc」其实是 HTML 或者 RTF 改名的，这种靠后缀路由必翻车。稳妥做法是读文件前几个字节判断魔数：.docx 的 ZIP 头是 PK（50 4B），.doc 的 OLE2 头是 D0 CF 11 E0。不过这个属于进阶校验，第一版可以不做，后面避坑章节会再提。

2.3 依赖引入的版本陷阱：poi-ooxml 和 poi-scratchpad 一个都不能少

只引入 poi 依赖是不够的。POI 解析 .docx 需要 poi-ooxml，解析 .doc 需要 poi-scratchpad，两者加上 poi 本体，一共三个 artifact。如果漏了 poi-scratchpad，HWPFDocument 类直接找不到。

我见过最典型的翻车是在 pom.xml 里只写了 poi-ooxml，结果运行时报错 NoClassDefFoundError。因为 poi-ooxml 会传递依赖 poi 和 poi-ooxml-lite，但不会带 poi-scratchpad。用 Maven 的同学顺手把三个依赖都写上，版本号保持一致，可以省去大量排查时间。

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>5.2.5</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-scratchpad</artifactId> <version>5.2.5</version> </dependency>

版本号建议统一用同一个，避免 poi 5.x 和 poi-ooxml 4.x 混用导致的 NoSuchMethodError。另外 POI 5.x 要求 JDK 8 及以上，如果你的服务还在 JDK 7，只能退回 4.1.2 版本，这条对老项目尤为重要。

3. 文本内容解析：段落、表格、图片一个都不能漏

3.1 从 XWPFDocument 中提取正文：遍历段落和表格的先后顺序决定内容完整性

很多人写 .docx 文本提取时，只遍历了 XWPFDocument 的 paragraphs 列表，结果发现文档里表格中的文字全部丢了。原因很简单：Word 文档中正文段落和表格在 XML 里是两类独立的元素，正文段落存在 /w:document/w:body 下的 w:p 节点，表格则是 w:tbl 节点。POI 把它们分别暴露成 getParagraphs() 和 getTables() 两个集合。

完整的提取逻辑应当是：按 body 元素内的顺序，同时处理段落和表格。POI 里 XWPFDocument 的 getBodyElements() 方法能返回按文档顺序排列的 body 级元素列表，每个元素要么是 XWPFParagraph，要么是 XWPFTable。按顺序遍历这个列表，就能保证「段落 — 表格 — 段落」这种混合排版的文档，提取出来的内容和视觉阅读顺序一致。

import org.apache.poi.xwpf.usermodel.*; import java.util.List; public String parseDocx(XWPFDocument doc) { StringBuilder content = new StringBuilder(); List<IBodyElement> bodyElements = doc.getBodyElements(); for (IBodyElement element : bodyElements) { if (element instanceof XWPFParagraph) { XWPFParagraph paragraph = (XWPFParagraph) element; content.append(paragraph.getText()).append("\n"); } else if (element instanceof XWPFTable) { XWPFTable table = (XWPFTable) element; for (XWPFTableRow row : table.getRows()) { List<String> cellTexts = new ArrayList<>(); for (XWPFTableCell cell : row.getTableCells()) { cellTexts.add(cell.getText()); } content.append(String.join(" | ", cellTexts)).append("\n"); } } } return content.toString(); }

我一般会把表格的每一行用竖线和换行符拼起来，这样既保留了表格的行结构，又不会让所有单元格连成一坨。参数方面，getText() 返回的段落文本会把段落内所有 run 的文字拼在一起，不包含换行符；cell.getText() 则可能包含单元格内部的段落换行，使用前最好做个 trim。如果你后续要把这段文本存进数据库做检索，建议在拼接时把连续多个空白字符压缩成一个空格，能显著降低存储量。

这段代码有一个隐含问题：没处理嵌入在文本段落中的图片。段落里如果插了图片，getText() 是取不到图片的，图片信息存在 run 的 embedded pictures 里。这个问题放到下一节专门讲。

3.2 提取文档中的图片：处理好 Word 的图片容器才能不丢附件

很多业务场景不只要文字，还要把 Word 里的图片也存下来。比如合同扫描件、带截图的测试报告、带流程图的需求说明。POI 里图片存在于两个位置：段落 run 的 embedded pictures，以及 XWPFPictureData 全局列表。

从 XWPFDocument 拿图片最简单的方式是调用 doc.getAllPictures()，它会返回文档中所有图片的 XWPFPictureData 列表，每个对象里有图片的字节数据和扩展名。保存时用图片的文件名或者自增 ID 作为文件名，写到本地磁盘或对象存储都行。数据库这边通常不直接存图片，而是存图片的相对路径或 URL，正文文本存 CLOB，这样文件系统负责大文件存储，数据库只存索引，性能更好。

import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFPictureData; public void savePictures(XWPFDocument doc, String saveDir) throws Exception { List<XWPFPictureData> pictures = doc.getAllPictures(); for (int i = 0; i < pictures.size(); i++) { XWPFPictureData pic = pictures.get(i); byte[] data = pic.getData(); String extension = pic.suggestFileExtension(); // 用文档内图片的索引作为文件名前缀，避免重名覆盖 String fileName = "pic_" + i + "." + extension; java.nio.file.Files.write( java.nio.file.Paths.get(saveDir, fileName), data ); } }

这里有个容易忽略的问题：getAllPictures() 返回的图片顺序不一定和它们在文档正文中的显示顺序一致。POI 内部按图片在包中的存储顺序排列，而不是视觉顺序。如果你的业务要求图片和文本段落严格对应，那得通过遍历 run 的 getEmbeddedPicturesList() 来定位每张图片，并且记录它所在的段落索引。第一版通常用不到这么细，但做图文混排的内容管理系统时一定会遇到。

suggestFileExtension() 返回的是规范化的小写扩展名，如 png、jpeg、emf。EMF 是 Windows 矢量格式，网页端直接展示会黑屏，这个后面避坑章节细说。

3.3 老 .doc 的内容提取：WordExtractor 比 HWPF 逐段解析更省心

针对 .doc 老文件，POI 提供了 WordExtractor 工具类，一行代码就能拿到全部文本。这比 HWPFDocument 里手动遍历 Paragraph 要省事很多，适合只关心文字内容的场景。

import org.apache.poi.hwpf.extractor.WordExtractor; import java.io.ByteArrayInputStream; public String parseDoc(byte[] fileBytes) throws Exception { try (WordExtractor extractor = new WordExtractor(new ByteArrayInputStream(fileBytes))) { // getText() 返回整个文档的纯文本，段落之间用换行符分隔 String text = extractor.getText(); // getTextFromPieces() 可以拿到带分页符的文本，适合需要保留分页信息的场景 return text; } }

WordExtractor 的 getText() 内部已经处理了段落、表格、页眉页脚等混合内容。但注意，它会把页眉页脚的内容也囊括进去。如果你的合同文本里页眉有公司名和保密级别，提取后全文检索时这些内容也会被索引。想要排除页眉页脚，需要手动遍历 HWPFDocument 的 Paragraph，这个代价比较高。我一般会在入库前用正则把特征明显的页眉行过滤掉，或者干脆接受它存在。

.doc 文件的图片提取比 .docx 麻烦不少。HWPF 里没有类似 getAllPictures() 的公共接口，需要自己解析 PicturesTable 类。这块代码比较绕，如果业务上确实要处理老 .doc 的图片，我通常建议用户转换格式或者单独用工具批量转成 .docx 再走统一通道。硬啃 PicturesTable 的成本高，收益小，不值得。

4. 数据库存储设计：二进制存文件还是 CLOB 存文本

4.1 两条路线对比：byte[] 适合原样归档，CLOB 适合内容检索

回到标题里「上传到数据库」这句话。上传这个词其实有歧义：是把 Word 文件的二进制内容写进数据库，还是把 Word 里的文本内容写进数据库？两条路线的技术栈完全不同，我先用对比表把差异摆出来。

对比维度	存二进制（byte[] / BLOB）	存文本（CLOB / TEXT）
本质	文件原样保存，像网盘	内容提取后保存，像笔记
还原能力	可随时下载还原成 Word	无法还原原始排版
检索能力	数据库无法直接搜内容	可 LIKE / FULLTEXT 搜索
存储开销	大，文件多大就多大	通常更小，文本比 docx 体积小
典型场景	OA 归档、合同存档	文本检索、敏感词过滤

实际项目里最常见的是两条腿走路：内容字段存文本供检索展示，文件本身上传 OSS 或本地磁盘，数据库冗余存一个文件二进制备份。如果用户明确要求「上传到数据库」，没有外部存储，那就把二进制直接放 BLOB。但请记住，BLOB 字段会让数据库备份文件变得巨大，恢复时间成倍增长，生产环境最好评估一下再决定。

我倾向的做法是：数据库表设计三列——file_name 存文件名、file_blob 存 BLOB 二进制、file_text 存 CLOB 抽取文本。这样既能检索又能下载还原，代价是存储空间翻倍，但对绝大多数系统来说可以接受。

4.2 建表语句和字段类型选择：MySQL 下 BLOB 和 LONGTEXT 够用

以 MySQL 为例，二进制字段用 BLOB 或 LONGBLOB，文本字段用 TEXT 或 LONGTEXT。Word 文件动辄几 MB，TEXT 类型最大 64KB 根本不够用，直接上 LONGTEXT；二进制同理用 LONGBLOB。

CREATE TABLE word_document ( id BIGINT AUTO_INCREMENT PRIMARY KEY, file_name VARCHAR(255) NOT NULL COMMENT '原始文件名', file_type VARCHAR(20) NOT NULL COMMENT 'doc 或 docx', file_size BIGINT NOT NULL COMMENT '文件字节数', file_blob LONGBLOB NOT NULL COMMENT '文件二进制内容', file_text LONGTEXT NULL COMMENT '抽取出的文本内容', created_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '入库时间' ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Word文档存储表';

utf8mb4 是必须的，因为 Word 文档里可能包含 emoji 和生僻字，utf8 存不下四字节字符。file_size 字段别看它小，作用很大——下载时给前端展示文件大小，做容量统计也靠它，顺手就记下来。

BLOB/TEXT 字段会影响 InnoDB 的行存储格式：默认的 DYNAMIC 行格式下，长度超过 768 字节的内容会存放在溢出页，查询时如果没用到这些字段，可以避免读取大对象开销。也就是说，不要随便 SELECT *，只查 id 和 file_name 时性能会好很多。

4.3 MyBatis 插入 BLOB 和 CLOB：用 byte[] 参数直接传，别转 Base64

用 MyBatis 操作 BLOB 字段，最常见的手法是直接传 byte[] 参数，MyBatis 的 JdbcType.BLOB 能自动处理。但很多新手会把 byte[] 转成 Base64 字符串再存，结果字段里存了膨胀 33% 的文本，取出来还得解码——这个操作其实多次一举，而且遇到大文件时 Base64 字符串拼接会让 MyBatis 的内存开销暴增。

// Mapper 接口 public interface WordDocumentMapper { int insertDocument(@Param("fileName") String fileName, @Param("fileType") String fileType, @Param("fileSize") long fileSize, @Param("fileBlob") byte[] fileBlob, @Param("fileText") String fileText); }

对应的 XML 里只两行关键配置：BLOB 字段用 jdbcType="BLOB"，CLOB 字段用 jdbcType="CLOB"。MySQL 驱动会把 Java 的 byte[] 和 String 正确写入对应字段。

注释说明：fileName 必须带上扩展名，后续下载还原时拼 Content-Disposition 要用；fileType 是用来区分 .doc 和 .docx 的路由关键词。insert 语句里不要直接 SELECT LAST_INSERT_ID()，除非你确认连接没有走连接池混用，否则拿 id 可以另开一个查询。

4.4 文件过大时怎么办：MySQL max_allowed_packet 是隐藏地雷

很多程序写好了，一传大文件就报错：Packet for query too large。这是 MySQL 的 max_allowed_packet 参数限制，默认 4MB 或 64MB 取决于版本。Word 文件超过这个值，INSERT 就会被拒绝。

解决办法是两个方向同时做。第一，程序层面限制上传文件大小，比如 Spring 的 multipart 配置里设置 max-file-size 为 20MB，超过就返回友好提示，不进数据库。第二，确认数据库参数足够大，用 SET GLOBAL max_allowed_packet=64 * 1024 * 1024 调整，MySQL 8.0 默认已到 64MB，一般够用。

连接池这层也有坑：Druid 或 HikariCP 的 socketTimeout 默认可能只有 30 秒，写入大文件时耗时超过 30 秒，客户端会提前断开，表现为「SQL 执行到一半就断了」。解决方式是调大 socketTimeout 到 60000 甚至 120000，同时测试真实写入耗时。

5. 上传实现与接口整合：Spring Boot 接收 MultipartFile 的完整链路

5.1 Controller 层设计：MultipartFile 转字节流要防内存溢出

Spring Boot 接收文件上传用的是 MultipartFile 接口，看着简单，但有个性能坑：默认配置下 Spring 会把整个上传文件读入内存。如果文件大、并发量高，服务器内存直接被撑爆。需要主动配置 Spring 的文件上传缓存阈值和临时目录。

@PostMapping("/upload") public Map<String, Object> uploadWord(@RequestParam("file") MultipartFile file) { // 入参校验必须放最前面，避免空指针和超大文件入库 if (file.isEmpty()) { throw new IllegalArgumentException("上传文件为空"); } String fileName = file.getOriginalFilename(); // 只处理 .doc 和 .docx，其他类型直接拒绝 if (!fileName.toLowerCase().endsWith(".doc") && !fileName.toLowerCase().endsWith(".docx")) { throw new IllegalArgumentException("仅支持 Word 文件"); } if (file.getSize() > 20 * 1024 * 1024) { throw new IllegalArgumentException("文件大小超过 20MB 限制"); } byte[] fileBytes = file.getBytes(); // 大文件此步耗时较长，属正常现象 String text; if (fileName.toLowerCase().endsWith(".docx")) { text = extractTextFromDocx(fileBytes); } else { text = extractTextFromDoc(fileBytes); } // 入库逻辑省略，参考上一节的 Mapper documentService.save(fileName, fileBytes, text); return Map.of("status", "success", "size", fileBytes.length); }

getBytes() 是将整个文件载入 JVM 堆内存，这一步对 20MB 的文件大约占用 20MB 堆，高峰期并发 50 个请求就是 1GB，很容易触发 Full GC。如果你的服务比较吃紧，可以用 file.transferTo() 先把文件落到临时磁盘，再从磁盘读取解析，但代码复杂度会上升。我一般建议：文件确实经常大于 10MB 时才走磁盘中转，否则 keep it simple。

文件类型校验这里是按后缀判断，配合前面说的魔数校验更好。生产环境里伪装文件名的情况不在少数，前端选了图片改名为 .docx 然后后台上传，解析时直接抛异常，用户体验很差。

5.2 Service 层事务边界：先解析后入库，解析失败不能留下半条数据

Service 层的设计要点是事务边界和日志。解析 Word 失败时，如果没有事务回滚，数据库里可能躺着一条 file_text 为 NULL 的记录，造成脏数据。正确写法如下。

@Service public class WordDocumentService { @Autowired private WordDocumentMapper mapper; @Transactional(rollbackFor = Exception.class) public void saveDocument(String fileName, byte[] fileBytes, String text) { WordDocument record = new WordDocument(); record.setFileName(fileName); record.setFileType(fileName.substring(fileName.lastIndexOf(".") + 1)); record.setFileSize(fileBytes.length); record.setFileBlob(fileBytes); // 解析失败的场景由调用方捕获，这里不再抛异常，便于日志记录 record.setFileText(text); mapper.insertDocument(record); } }

rollbackFor = Exception.class 必须写，因为 Spring 默认只回滚 RuntimeException，解析 Word 抛出的 IOException 属于受检异常，不写 rollbackFor 会导致部分字段已写入而文本解析失败时事务不回滚。这个问题排查起来特别隐蔽，表现就是「明明传了空文件，库里却有一条记录」。

解析逻辑如果很耗时，比如大文档图片多，建议把解析放进线程池，请求先返回「处理中」状态，然后用轮询或回调通知结果。这是后话了，第一版同步处理能跑通即可。

5.3 下载还原：用 ResponseEntity 输出字节流，文件名要做 URL 编码

存进数据库的 BLOB，最终大概率要能下载。用 ResponseEntity<byte[]> 输出最直白，但有两个细节：一是文件名要处理成 RFC 5987 编码，否则中文文件名在浏览器里乱码；二是 Content-Type 要准确，.doc 和 .docx 的 MIME 类型不同。

@GetMapping("/download/{id}") public ResponseEntity<byte[]> download(@PathVariable Long id) { WordDocument doc = mapper.selectById(id); if (doc == null) { return ResponseEntity.notFound().build(); } String mimeType = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"; if ("doc".equalsIgnoreCase(doc.getFileType())) { mimeType = "application/msword"; } // 使用 URLEncoder 编码文件名，兼容浏览器中文文件名乱码问题 String encodedName = java.net.URLEncoder.encode(doc.getFileName(), StandardCharsets.UTF_8); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''" + encodedName) .contentType(MediaType.parseMediaType(mimeType)) .body(doc.getFileBlob()); }

attachment 参数是强制浏览器走下载，而不是直接打开预览。如果希望浏览器能预览 .docx（比如集成在线预览服务），要改成 inline。但浏览器原生不支持渲染 .docx，inline 基本是白搭。所以按附件下载是最稳的。

这里要提一句 BLOB 读取的内存问题：mapper.selectById(id) 会把整个 LONGBLOB 加载进堆内存。对于几百 MB 的巨型文件，这种做法直接 OOM。如果存在超大文件场景，应该用流式读取，MyBatis 配合 CLOB/BLOB 的流式处理比较繁琐，可以换用 JPA 的 @Lob 或者直接 JDBC 的 getBinaryStream。业务量不大时，byte[] 方案省事很多。

6. 避坑清单：读取 Word 入库最容易翻车的 6 个真实案例

6.1 损坏的 .docx 文件导致 parse 直接崩溃

现象：用户上传了一个从微信聊天记录里存下来的 Word 文件，后端日志报 ZipException: invalid entry size，整数入库流程中断。

原因：.docx 本质是 ZIP 包，微信传输、断点下载等场景容易造成文件不完整或文件头损坏。POI 遇到损坏的 ZIP 包会直接抛异常，不会给你任何机会。

解决：在解析前对字节流做一次 ZIP 完整性快速校验。用 java.util.zip.ZipInputStream 尝试读取条目，遇到任何异常就返回「文件已损坏」提示，不让它进入 POI 的解析逻辑。这个校验成本很低，约几毫秒，但对用户体验提升非常明显：至少用户知道是文件坏了，而不是系统出 bug 了。

public boolean isValidDocx(byte[] data) { try (java.util.zip.ZipInputStream zis = new java.util.zip.ZipInputStream(new ByteArrayInputStream(data))) { ZipEntry entry; while ((entry = zis.getNextEntry()) != null) { // 只遍历不解压，检查 ZIP 结构是否完整 } return true; } catch (Exception e) { return false; } }

注意 ZIP 完整性校验无法检测「文件内容被截断但结构恰好完整」的极端情况，但对绝大多数损坏场景有效。配合 .docx 的魔数判断（文件头是 PK），能拦截掉九成的问题文件。

6.2 文本提取结果乱码：编码问题还是 POI 版本问题

现象：从 .doc 文件提取出的中文变成菱形问号，一串 �。

原因：老 .doc 文件的文本编码取决于创建它的操作系统和 Office 版本。中文 Windows 下通常以 GBK 或 GB2312 存储，而 POI 的旧版本在未指定编码时可能误判为其他编码。实测 POI 4.x 和 5.x 对 .doc 编码的支持有明显差异，5.2 版本对中文 .doc 已经比较友好，旧版本就比较惨。

解决：优先升级 POI 到 5.2.x 版本，它是目前社区测过中文支持最好的稳定线。如果升级后仍乱码，检查系统默认字符集是否被设置为非 UTF-8（比如某些服务器的 LANG=C），在启动参数里加 -Dfile.encoding=UTF-8，能解决大部分「本地正常、服务器乱码」的诡异问题。

这个坑的隐蔽性在于：本地开发电脑通常是中文编码，服务器往往是英文系统编码，两个环境跑同样的代码结果不一样。排查时先对比两边的 file.encoding 参数，十有八九能定位问题。

6.3 大量文本入库超过 MySQL 单行限制

现象：插入总是报 Row size too large，但只要把 file_text 字段去掉就能正常插入。

原因：MySQL 的 InnoDB 单行字节数受限于页大小，默认 16KB，但 BLOB/TEXT 字段有自己的溢出存储机制，理论上不该撑爆行。实际上如果表里同时有很多 VARCHAR 列，且 TEXT 字段在行内保留了前 768 字节，综合计算可能超限。

解决：把 TEXT 字段从主表拆到子表，单独一张 word_text（word_id, file_text），一对一关系。这样主表行瘦身，TEXT 表只有两个字段，几乎不会触发行大小限制。另外一个偏方是调整 innodb_page_size，但这是全局参数，改动代价太大，不如拆表干净。

6.4 EMF 图片在 Web 端显示为黑块

现象：Word 文档里的流程图、矢量图插入数据库后，前端展示图片区域一片黑。

原因：Word 内部会保存两种图片版本：原始嵌入格式（如 PNG）和兼容用的 EMF 版本。POI 的 getAllPictures() 优先返回 EMF 格式的数据。EMF 是 Windows 矢量元文件，现代浏览器基本不支持渲染。

解决：在保存图片前做格式过滤，优先选择 png 或 jpeg 格式的 XWPFPictureData。如果列表里只有 EMF，可以用 Apache Batik 或 图片处理工具转成 PNG 再存。代码上就是遍历 getAllPictures() 时检查 suggestFileExtension()，过滤掉 emf。这条坑在生成缩略图时尤其常见，处理不好就是前端一堆黑块。

6.5 多线程并发解析 Word 导致内存溢出

现象：上传高峰期服务 CPU 打满，然后连续 OOM，服务重启后正常。

原因：每个上传请求都独立创建 XWPFDocument 并加载完整字节流到内存，20MB 文件在解析时的临时对象可能膨胀到 500MB 以上（XML DOM 树 + 字符串缓存），并发 10 个请求就吃掉 5GB 堆。

解决：限制并发数量，用信号量或线程池把解析请求排队。同时给解析线程设置超时，超过 30 秒强制降级返回「文件结构太复杂，请转存 PDF 后上传」。还有一个思路是分布式拆出去：把 Word 解析单独部署一个解析服务，主服务接收上传后投递到消息队列，异步解析异步入库。对于文件量大、并发高的系统，这个架构迟早要上。

6.6 Base64 交换 BLOB 导致的性能哑火

现象：插入成功后，功能正常，但数据库体积暴涨，查询列表也越来越慢。

原因：代码里为了「方便」把 byte[] 转成 Base64 字符串再入 LONGTEXT 字段，Base64 膨胀率约 33%，而且 LONGTEXT 里全是大写字母和符号，压缩率差，InnoDB 的页缓存利用率极低。

解决：BLOB 就老老实实用 byte[] 参数传，不需要人为编码。如果一定要走文本通道，也请使用 JdbcType.BLOB。这个坑在多人协作项目里特别容易出现——接手的人看到 BLOB 觉得「不好打印日志」，就擅自改成 Base64，然后全库埋雷。

7. 进阶：全文检索、在线预览和异步解析的进化方向

当基础的「读取并入库」跑通后，你会很快遇到三个新需求：内容搜索、在线预览、超大文件上传。这三个方向都有现成方案，但各有取舍。

内容搜索上，MySQL 的 LIKE '%关键词%' 在数据量超过十万条时性能断崖式下跌。这时候得考虑引入 Elasticsearch 或 Meilisearch，把 file_text 字段同步建索引。同步方式建议走 Canal 监听 binlog，或者应用层双写。如果项目不大，MySQL 8.0 的全文索引（FULLTEXT）能顶一阵，但要记得把 file_text 改成没有标点的纯文本，分词效果才理想。还有个轻量方案是 SQLite FTS5，适合单机小项目，但并发写差，不太建议作为主存储。

在线预览 Word 是一个比解析入库更复杂的问题，因为浏览器不原生支持 .docx 渲染。常见路线是把 docx 转 PDF 再通过 PDF 预览组件展示。这一步推荐用 LibreOffice headless 模式命令行转换，稳、免费、格式还原度高。JVM 相关的 docx4j 转换 PDF 有字体缺失风险，中文字体和样式可能错乱，实际效果不如 LibreOffice。转换后的 PDF 存另一张表或对象存储，预览时直接拉流。转换服务的资源开销较大，建议独立部署，别跟业务应用抢内存。

异步解析是我个人最推荐的架构演进方向。上传接口收到文件后直接存库，状态置为 PROCESSING，同时把文件 ID 丢进阻塞队列或 RocketMQ。解析服务消费任务、抽取文本、更新状态。前端轮询 GET /status/{id}，看见状态变 SUCCESS 就刷新页面。这样做的好处是接口响应时间从几秒降到几十毫秒，用户体验和系统稳定性都上了一个台阶。代价是要维护一套任务状态机和重试机制。我习惯用一张 task 表记录每个文件的解析次数和错误信息，解析失败能直接看到原因。

最后说一个查问题的习惯：每次解析出错，别急着看业务代码，先把原始文件拉出来手动用 Office 打开。如果 Office 打开也报损坏或修复，那问题大概率不在你的代码里，让用户重新导出才是正解。如果是 Office 能开但你的程序不行，再查 POI 版本、编码、图片格式这些点。这个排查顺序能帮你省掉很多无效 Debug 的夜晚。

写这套代码时我翻车的最大一次，就是把 .doc 的老文件全量导入新系统，结果 HWPF 解析表格时把单元格内容挤成了一行，所有合同的金额和日期全串位了。从那以后我对老 .doc 的表格解析都加了一层按行分隔的校验。希望这几条踩坑经验能帮你少走几步弯路。

本文还有配套的精品资源，点击获取