Part 09 Unit 01

常見問題診斷

快速找出並解決 Pandoc 轉換問題

                學習目標
                認識最常見的轉換錯誤
學會系統性的問題診斷方法
建立問題排查清單
快速定位問題根源

            

問題診斷的正確心態

                遇到錯誤時...
                不要慌張 - 錯誤訊息是你的朋友
仔細閱讀 - 錯誤訊息通常已說明原因
系統排查 - 按步驟一一確認
善用工具 - AI 可以幫你分析

            

記住：每個錯誤都是學習的機會！解決過一次，下次就知道怎麼處理了。

常見錯誤類型總覽

1. 檔案相關錯誤

找不到檔案、路徑錯誤、權限問題

2. 格式相關錯誤

YAML 語法錯誤、Markdown 格式問題

3. 編碼相關錯誤

檔案編碼不正確、亂碼問題

4. 轉換相關錯誤

缺少依賴、格式不支援

問題 1：檔案不存在

錯誤訊息

pandoc: input.md: openFile: does not exist (No such file or directory)

可能原因

檔案名稱拼錯
檔案不在當前目錄
路徑中有特殊字元

解決方法

1. 確認檔案名稱拼寫正確

2. 使用完整路徑（如 D:\docs\input.md）

3. 用 dir 或 ls 確認檔案存在

問題 2：YAML 解析錯誤

錯誤訊息

pandoc: Could not parse YAML header

常見原因

開頭或結尾的 --- 缺少或不完整
縮排不一致（混用空格和 Tab）
特殊字元未正確跳脫

正確的 YAML 格式

                    ---
title: 文件標題
author: 作者名
date: 2024-01-01
---
                

YAML 錯誤對照表

錯誤示範 ❌

                ---
title:文件標題      # 冒號後沒空格
author: "作者"名    # 引號沒配對
  date: 2024        # 縮排錯誤
--                  # 結尾少一個 -
            

正確示範 ✓

                ---
title: 文件標題
author: "作者名"
date: 2024
---
            

問題 3：編碼錯誤

錯誤訊息

pandoc: Cannot decode byte sequence... invalid byte sequence

原因

檔案不是 UTF-8 編碼（可能是 Big5、GB2312 等）

解決方法

1. 用記事本開啟檔案

2. 選擇「另存新檔」

3. 編碼選擇「UTF-8」

4. 儲存後重新轉換

用 PowerShell 轉換編碼

                # 將檔案轉換為 UTF-8 編碼
$content = Get-Content "old-file.md" -Encoding Default
$content | Out-File "new-file.md" -Encoding UTF8

# 批次轉換整個資料夾
Get-ChildItem *.md | ForEach-Object {
    $content = Get-Content $_.FullName -Encoding Default
    $content | Out-File $_.FullName -Encoding UTF8
    Write-Host "已轉換: $($_.Name)"
}
            

小技巧：養成習慣，建立新檔案時就使用 UTF-8 編碼！

問題 4：圖片找不到

錯誤訊息

pandoc: Could not find image 'images/photo.png'

可能原因

圖片路徑寫錯
圖片檔案不存在
使用了絕對路徑但檔案位置變了

解決方法

確保圖片和 Markdown 的相對位置正確

                    project/
├── document.md
└── images/
    └── photo.png

# 在 document.md 中使用：
![圖片說明](images/photo.png)
                

問題 5：PDF 引擎找不到

錯誤訊息

pdflatex not found. Please select a different --pdf-engine

原因

系統沒有安裝 LaTeX（Pandoc 轉 PDF 需要）

解決方法

方法 1：安裝 MiKTeX（推薦，較小）
方法 2：安裝 TeX Live（完整，較大）
方法 3：先轉成 HTML 或 DOCX，再另存 PDF

系統性問題診斷流程

1閱讀錯誤訊息 - 找出關鍵字

2確認輸入 - 檔案存在？路徑對？

3簡化測試 - 用最簡單的指令測試

4逐步增加 - 一次加一個選項

5尋求幫助 - 請 AI 分析錯誤

診斷檢查清單

Pandoc 已正確安裝？（執行 pandoc --version）
輸入檔案存在？（路徑正確？）
檔案編碼是 UTF-8？
YAML 標頭格式正確？
圖片路徑正確且檔案存在？
輸出目錄有寫入權限？
（PDF）LaTeX 已安裝？
指令參數拼寫正確？

使用 --verbose 取得詳細資訊

                # 顯示詳細的轉換過程
pandoc input.md -o output.docx --verbose
            

verbose 輸出會顯示：

正在處理哪些檔案
使用哪個 writer
處理的每個步驟
詳細的錯誤位置

遇到問題時，先加上 --verbose 再執行一次！

簡化測試法

步驟一：建立最簡單的測試檔

                # test.md
Hello World
            

步驟二：執行最簡單的轉換

pandoc test.md -o test.html

步驟三：逐步增加複雜度

如果簡單的成功，再慢慢加入 YAML、圖片、選項等

實作：建立診斷腳本

請 AI 幫你建立

                請幫我建立一個 Pandoc 診斷腳本，
可以檢查：
Pandoc 是否安裝
輸入檔案是否存在
檔案編碼是否正確
YAML 標頭是否有效
執行測試轉換
            

診斷腳本範例

                # diagnose.ps1
param([string]$File)

Write-Host "=== Pandoc 診斷 ===" -ForegroundColor Cyan

# 1. 檢查 Pandoc
Write-Host "`n[1] Pandoc 安裝:" -NoNewline
try {
    $v = pandoc --version | Select-Object -First 1
    Write-Host " OK ($v)" -ForegroundColor Green
} catch {
    Write-Host " 未安裝!" -ForegroundColor Red
    exit
}

# 2. 檢查檔案
Write-Host "[2] 檔案存在:" -NoNewline
if (Test-Path $File) {
    Write-Host " OK" -ForegroundColor Green
} else {
    Write-Host " 找不到檔案!" -ForegroundColor Red
    exit
}

# 3. 測試轉換
Write-Host "[3] 測試轉換:" -NoNewline
try {
    pandoc $File -o "$env:TEMP\test.html"
    Write-Host " OK" -ForegroundColor Green
} catch {
    Write-Host " 失敗" -ForegroundColor Red
    Write-Host "    錯誤: $_"
}
            

常見錯誤速查表

錯誤關鍵字	快速解法
does not exist	檢查檔案路徑
YAML header	檢查 --- 標記和縮排
byte sequence	轉換為 UTF-8 編碼
image	確認圖片路徑和檔案
pdflatex	安裝 LaTeX 或改用其他格式
permission	檢查檔案/資料夾權限

實作練習

任務：練習問題診斷

1建立一個有 YAML 錯誤的 Markdown 檔

2嘗試轉換，觀察錯誤訊息

3使用 --verbose 查看詳細資訊

4修正錯誤，成功轉換

預防勝於治療

                好習慣養成
                統一使用 UTF-8 - 建立新檔案時就設定好
檔名不用空格 - 用底線或連字號代替
相對路徑 - 方便移動整個專案
先測試後執行 - 批次處理前先測一個
定期備份 - 避免意外覆蓋重要檔案

            

小測驗

看到「Could not parse YAML header」錯誤，最可能的原因是？

本單元總結

                學到的技巧
                認識 5 種最常見的錯誤類型
學會系統性診斷流程
使用 --verbose 取得詳細資訊
簡化測試法定位問題
預防問題的好習慣

            

下一步：在 Unit 02 學習環境設定問題的解決方法