PPTX/docs/troubleshooting.md

故障排查

本文档提供常见问题的解决方法。

常见错误

文件不存在: xxx.yaml

原因：找不到输入文件

解决方法：

• 检查文件路径是否正确
• 确认文件在当前目录或使用相对/绝对路径
• 检查文件名拼写是否正确

# 错误示例
uv run yaml2pptx.py convert presntation.yaml  # 拼写错误

# 正确示例
uv run yaml2pptx.py convert presentation.yaml

YAML 语法错误: 第 X 行

原因：YAML 格式错误

解决方法：

• 检查缩进是否正确（使用空格，不要使用 Tab）
• 确保冒号后有空格
• 检查引号是否成对
• 使用 YAML 验证工具检查语法

# 错误示例
slides:
- elements:  # 缩进错误
  - type: text
content: "hello"

# 正确示例
slides:
  - elements:
      - type: text
        content: "hello"

模板文件不存在: xxx

原因：模板文件未找到

解决方法：

• 检查 --template 参数是否正确
• 确认模板库文件存在
• 检查模板名称拼写

# 错误示例
uv run yaml2pptx.py convert presentation.yaml --template ./templat.yaml  # 拼写错误

# 正确示例
uv run yaml2pptx.py convert presentation.yaml --template ./templates.yaml

缺少必需变量: xxx

原因：未提供必需的模板变量

解决方法：

• 在 vars 中提供该变量
• 检查模板定义中哪些变量是 required: true

# 模板定义
templates:
  title-slide:
    vars:
      - name: title
        required: true

# 错误示例
- template: title-slide
    vars: {}  # 缺少 title

# 正确示例
- template: title-slide
    vars:
      title: "我的标题"

图片文件未找到: xxx

原因：图片文件不存在

解决方法：

• 检查图片路径是否正确
• 确认图片文件存在
• 使用相对路径（相对于 YAML 文件位置）

# 错误示例
- type: image
  src: "images/logo.png"  # 文件不存在

# 正确示例
- type: image
  src: "../assets/logo.png"  # 使用正确的相对路径

无效的颜色格式: xxx

原因：颜色格式不符合要求

解决方法：

• 使用 #RGB 或 #RRGGBB 格式
• 不要使用颜色名称（如 red、blue）

# 错误示例
font:
  color: "red"

# 正确示例
font:
  color: "#ff0000"

其他问题

元素超出页面范围

警告：元素右边界超出: 10.50 > 10

说明：元素的右边界超出了幻灯片宽度

解决方法：

• 调整元素的 box 尺寸
• 确保元素在页面范围内
• 0.1 英寸内的超出是允许的

# 16:9 幻灯片，最大宽度 10"
# 错误示例
box: [1, 1, 9, 1]  # 右边界 = 1 + 9 = 10"（警告）

# 正确示例
box: [1, 1, 8.9, 1]  # 右边界 = 1 + 8.9 = 9.9"（正常）

模板名称冲突

警告：模板名称冲突: 'title-slide'

说明：内联和外部模板同名

解决方法：

• 重命名其中一个模板
• 系统会优先使用内联模板

字体大小过小

警告：字体大小过小: 5

说明：字体小于 6pt 可能难以阅读

解决方法：

• 增加字体大小到至少 6pt
• 建议使用 12pt 以上

调试技巧

使用验证功能

# 在转换前验证
uv run yaml2pptx.py check presentation.yaml

使用预览模式

# 实时查看效果
uv run yaml2pptx.py preview presentation.yaml

检查 YAML 语法

使用在线 YAML 验证工具：

• https://www.yamllint.com/
• https://yaml-online-parser.appspot.com/

查看详细错误

使用 -v 参数查看详细输出：

uv run python -c "
import yaml
with open('presentation.yaml') as f:
    yaml.safe_load(f)
"

获取帮助

如果以上方法无法解决问题：

1. 查看 开发文档 了解更多信息
2. 检查 GitHub Issues
3. 提交新的 Issue，包含：
   • 完整的错误信息
   • YAML 文件内容（脱敏后）
   • 使用的命令
   • 系统环境信息

返回文档索引