PPTX/docs/troubleshooting.md

# 故障排查

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

## 常见错误

### 文件不存在: xxx.yaml

**原因**：找不到输入文件

**解决方法**：
- 检查文件路径是否正确
- 确认文件在当前目录或使用相对/绝对路径
- 检查文件名拼写是否正确

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

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

### YAML 语法错误: 第 X 行

**原因**：YAML 格式错误

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

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

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

### 模板文件不存在: xxx

**原因**：模板文件未找到

**解决方法**：
- 检查 `--template` 参数是否正确
- 确认模板库文件存在
- 检查模板名称拼写

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

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

### 缺少必需变量: xxx

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

**解决方法**：
- 在 `vars` 中提供该变量
- 检查模板定义中哪些变量是 `required: true`

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

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

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

### 图片文件未找到: xxx

**原因**：图片文件不存在

**解决方法**：
- 检查图片路径是否正确
- 确认图片文件存在
- 使用相对路径（相对于 YAML 文件位置）

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

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

### 无效的颜色格式: xxx

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

**解决方法**：
- 使用 `#RGB` 或 `#RRGGBB` 格式
- 不要使用颜色名称（如 `red`、`blue`）

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

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

## 其他问题

### 元素超出页面范围

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

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

**解决方法**：
- 调整元素的 `box` 尺寸
- 确保元素在页面范围内
- 0.1 英寸内的超出是允许的

```yaml
# 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 以上

## 调试技巧

### 使用验证功能

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

### 使用预览模式

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

### 检查 YAML 语法

使用在线 YAML 验证工具：
- https://www.yamllint.com/
- https://yaml-online-parser.appspot.com/

### 查看详细错误

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

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

## 获取帮助

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

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

[返回文档索引](../README.md)