Apache POI 5.0.0 在创建或修改 .pptx 文件时，若未显式设置 XSLFTextRun 的文本内容（即使为空字符串），会导致 PowerPoint 拒绝打开并报“文件已损坏”，尽管其他工具可正常读取——根本原因在于未初始化的文本运行节点违反了 OOXML 规范。
apache poi 5.0.0 在创建或修改 .pptx 文件时，若未显式设置 `xslftextrun` 的文本内容（即使为空字符串），会导致 powerpoint 拒绝打开并报“文件已损坏”，尽管其他工具可正常读取——根本原因在于未初始化的文本运行节点违反了 ooxml 规范。
在使用 Apache POI 处理 PowerPoint（.pptx）文件时，尤其是基于模板动态填充内容的场景，开发者常误以为「创建对象即完成初始化」。但事实是：POI 的 XSLFTextRun 等核心文本组件必须显式调用 setText(...)，否则其底层 XML 结构将缺失必需的 <t></t>（text）元素，导致生成的 .pptx 虽能被 ZIP 工具解压、被 LibreOffice 或在线查看器兼容，却无法通过 Microsoft PowerPoint 的严格 OOXML 架构校验（如 presentation.xml 中引用的 rId 关联的 slideN.xml 内存在空 <br> 或无 <t></t> 的 <r></r> 节点），从而触发“文件已损坏，是否尝试修复？”提示。
成品ppt在线生成，百种模板可供选择☜☜☜☜☜点击使用；
该问题与 setSlideOrder() 等幻灯片排序操作完全无关——正如用户实测所见：getSlides() 遍历显示序号正常，ZIP 解包后内容字节一致，仅内部 XML 引用关系因非法文本节点而失效。真正罪魁是看似无害的“未赋值文本运行”：
// ❌ 危险：创建 XSLFTextRun 后未调用 setText()
XSLFTextParagraph paragraph = textbox.addNewTextParagraph();
XSLFTextRun run = paragraph.addNewTextRun();
// run.setText("..."); ← 此行被遗漏！上述代码会生成不合规的 <r><rpr ...></rpr></r>（缺少 <t></t>），PowerPoint 将其视为结构损坏。
✅ 正确做法是：任何新建的 XSLFTextRun 必须立即设置文本内容——即使是空字符串：
// ✅ 安全：显式设置文本（空字符串亦可）
XSLFTextParagraph paragraph = textbox.addNewTextParagraph();
XSLFTextRun run = paragraph.addNewTextRun();
run.setText(""); // 或 run.setText("Hello, POI!");同理，此规则适用于所有涉及文本内容的场景：
- 表格单元格内文本（
XSLFTableCell.setText(...)或其子XSLFTextParagraph中的XSLFTextRun） - 形状内文本框（
XSLFTextBox） - 标题/副标题占位符（通过
slide.getPlaceholder(...)获取后操作）
⚠️ 注意事项：
- 不要依赖
setText(null)：POI 5.x 会抛出NullPointerException，必须传入String（推荐""表示空）。 - 使用
XSLFTable时，务必对每个XSLFTableCell调用setText("")或填充内容，避免其内部XSLFTextParagraph的XSLFTextRun处于未初始化状态。 - 若需批量清理/校验，可在保存前添加轻量级验证逻辑：
// 保存前检查所有 TextRun 是否已初始化（可选）
for (XSLFSlide slide : presentation.getSlides()) {
for (XSLFShape shape : slide.getShapes()) {
if (shape instanceof XSLFTextShape) {
for (XSLFTextParagraph para : ((XSLFTextShape) shape).getTextParagraphs()) {
for (XSLFTextRun run : para.getTextRuns()) {
if (run.getRawText() == null || run.getRawText().isEmpty()) {
run.setText(""); // 强制补全
}
}
}
}
}
}? 总结：POI 5.0.0+ 的 .pptx 损坏问题本质是 OOXML 合规性缺陷，而非 API 使用错误。牢记「创建即设置」原则——只要涉及 XSLFTextRun、XSLFTableCell.setText()、XSLFTextShape.setText() 等接口，就必须提供非 null 字符串（哪怕为空）。这一实践不仅能规避 PowerPoint 兼容性问题，也符合 ISO/IEC 29500 标准对 PresentationML 文档结构的强制要求。
