Part 03 Unit 03 - 常見錯誤與解決方案
📘 FB 🎥 YT

Part 03 - Pandoc 安裝與基礎轉換

Unit 03: 常見錯誤

遇到問題別慌！這裡有解答

疑難排解 錯誤訊息 解決方案

本單元學習目標

1️⃣

識別錯誤訊息

看懂 Pandoc 的錯誤提示

2️⃣

解決常見問題

學會處理最常遇到的錯誤

3️⃣

預防錯誤

養成好習慣，避免錯誤發生

4️⃣
自我排解

學會獨立解決問題的方法

錯誤 1：找不到 pandoc 指令

'pandoc' is not recognized as an internal or external command

或

pandoc: command not found

原因

  • Pandoc 尚未安裝
  • 安裝後沒有重新開啟終端機
  • Pandoc 沒有加入系統 PATH

錯誤 1 解決方案

✅ 解決步驟

步驟 1：關閉所有終端機視窗

步驟 2：重新開啟 Antigravity

步驟 3：開啟新的終端機，再試一次 pandoc --version

步驟 4：如果還是不行，重新安裝 Pandoc

關鍵：安裝後一定要重新開啟終端機！

錯誤 2：找不到輸入檔案

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

原因

  • 檔案名稱打錯
  • 檔案不在目前的資料夾
  • 檔案副檔名錯誤（例如 .txt 打成 .md）

錯誤 2 解決方案

✅ 解決步驟

步驟 1：確認檔案名稱正確

dir *.md　　# Windows
ls *.md　　　# Mac/Linux

步驟 2：確認終端機在正確的資料夾

pwd　　# 顯示目前資料夾

步驟 3：使用 Tab 鍵自動補全檔名

技巧：輸入 pandoc sam 然後按 Tab 會自動補全成 pandoc sample.md

錯誤 3：檔名含空格

pandoc: my: openFile: does not exist

執行的指令：

pandoc my report.md -o my report.docx　❌ 錯誤

原因

空格會被解讀成參數分隔，所以 Pandoc 只看到 my，找不到這個檔案。

錯誤 3 解決方案

✅ 正確寫法：用引號包起來

pandoc "my report.md" -o "my report.docx"　✅ 正確
最佳實踐：建議檔名不要用空格！用底線或連字號代替：
  • my_report.md ✅
  • my-report.md ✅
  • myReport.md ✅

錯誤 4：中文檔名問題

pandoc: 報告.md: openFile: does not exist

原因

  • 終端機編碼問題
  • 某些系統對中文檔名支援不完整

✅ 解決方案

  1. 用引號包起來：pandoc "報告.md" -o "報告.docx"
  2. 或改用英文檔名（推薦）

錯誤 5：輸出檔案被佔用

pandoc: sample.docx: openBinaryFile: permission denied (Permission denied)

原因

輸出的 .docx 檔案正在 Word 中開啟，無法覆寫。

✅ 解決方案

  1. 關閉 Word 中開啟的該檔案
  2. 重新執行 Pandoc 指令
提醒：轉換前先關閉相關的 Word 檔案！

錯誤 6：指令語法錯誤

pandoc: unrecognized option '--output'

常見語法錯誤

❌ 錯誤 ✅ 正確
pandoc -o sample.md sample.docx pandoc sample.md -o sample.docx
pandoc --output sample.docx pandoc sample.md -o sample.docx
正確語法：pandoc [輸入檔] -o [輸出檔]

除錯技巧 1：使用 Tab 自動補全

⌨️ 輸入部分檔名後按 Tab 鍵

pandoc sam[按 Tab] → pandoc sample.md

好處

  • ✅ 自動補全正確的檔名
  • ✅ 避免打字錯誤
  • ✅ 確認檔案確實存在
如果按 Tab 沒反應：表示找不到符合的檔案，檢查檔名或資料夾！

除錯技巧 2：先列出檔案

執行 Pandoc 前，先確認檔案存在：

Windows (PowerShell)

dir　　　　　　# 列出所有檔案
dir *.md　　　# 只列出 .md 檔案

macOS / Linux

ls　　　　　　# 列出所有檔案
ls *.md　　　# 只列出 .md 檔案

除錯技巧 3：讓 AI 幫忙

遇到錯誤時，可以把錯誤訊息貼給 AI：

在 AI 面板輸入：

我執行 pandoc sample.md -o sample.docx 出現這個錯誤：
pandoc: sample.md: openFile: does not exist
請幫我解決
AI 會幫你：分析錯誤原因並提供解決步驟！

預防錯誤的好習慣

📝

1. 檔名用英文

避免中文和特殊字元

_

2. 不用空格

用底線 _ 或連字號 - 代替

🔤

3. 全小寫

避免大小寫混淆

💾

4. 先儲存

轉換前確認檔案已儲存

好檔名範例：project_report.md、meeting-notes.md

錯誤速查表

錯誤訊息關鍵字 原因 解決方案
not recognized Pandoc 未安裝/未載入 重開終端機或重新安裝
does not exist 找不到檔案 檢查檔名和路徑
permission denied 檔案被佔用 關閉開啟該檔案的程式
unrecognized option 參數錯誤 檢查指令語法

隨堂測驗 1

問題：檔名含有空格時，應該怎麼處理？

  1. 把空格刪掉
  2. 用引號把檔名包起來
  3. 用逗號代替空格
  4. 無法處理，只能改檔名

✅ 測驗 1 解答

答案：(2) 用引號把檔名包起來

範例：pandoc "my report.md" -o "my report.docx"

不過最好的做法是：一開始就不要用空格命名檔案！

隨堂測驗 2

問題：執行 pandoc sample.md -o sample.docx 出現「permission denied」錯誤，最可能的原因是？

  1. Pandoc 沒有安裝
  2. sample.md 不存在
  3. sample.docx 正在 Word 中開啟
  4. 電腦沒有網路

✅ 測驗 2 解答

答案：(3) sample.docx 正在 Word 中開啟

解釋：「permission denied」表示無法寫入檔案，通常是因為該檔案正被其他程式（如 Word）佔用。關閉 Word 後重試即可。

Part 03 完整總結

📥

Unit 01

成功安裝 Pandoc 並驗證

🔄

Unit 02

完成第一次 .md → .docx 轉換

🔧

Unit 03

學會處理常見錯誤

🎉 恭喜完成 Part 03！

你已經掌握 Pandoc 的基本操作！

下一步：Part 04 - 在 Antigravity 中用 AI 輔助執行 Pandoc！