Part 09 Unit 02

環境設定問題

解決安裝和設定的各種疑難雜症

                學習目標
                解決 Pandoc 安裝問題
設定正確的環境變數
處理 PATH 相關問題
安裝必要的相依套件

            

常見環境設定問題

1. 「找不到 pandoc 命令」

Pandoc 沒有加入 PATH

2. 「pdflatex not found」

缺少 LaTeX 環境

3. 「無法執行腳本」

PowerShell 執行原則限制

4. 「版本太舊」

需要更新 Pandoc

問題 1：找不到 pandoc 命令

錯誤訊息

pandoc : 無法辨識 'pandoc' 詞彙是否為 Cmdlet、函數、指令檔或可執行程式的名稱。

原因

Pandoc 沒有安裝，或沒有加入系統 PATH

解決步驟

1. 確認 Pandoc 已安裝

2. 將 Pandoc 加入 PATH 環境變數

檢查 Pandoc 是否安裝

方法 1：直接測試

pandoc --version

方法 2：找到安裝位置

                # 常見安裝位置
Test-Path "C:\Program Files\Pandoc\pandoc.exe"
Test-Path "C:\Users\$env:USERNAME\AppData\Local\Pandoc\pandoc.exe"
            

方法 3：搜尋檔案

Get-ChildItem -Path C:\ -Name pandoc.exe -Recurse -ErrorAction SilentlyContinue

安裝 Pandoc

方法 1：官網下載（推薦）

1前往 pandoc.org

2下載 Windows 安裝檔 (.msi)

3執行安裝，勾選「加入 PATH」

方法 2：用 Winget 安裝

winget install --id JohnMacFarlane.Pandoc

方法 3：用 Chocolatey 安裝

choco install pandoc

手動設定 PATH 環境變數

1按 Win + R，輸入 sysdm.cpl

2點選「進階」→「環境變數」

3在「系統變數」找到 Path，點「編輯」

4點「新增」，加入 Pandoc 路徑：

C:\Program Files\Pandoc

5確定後，重新開啟 PowerShell 測試

用 PowerShell 設定 PATH

                # 取得目前的 PATH
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")

# 加入 Pandoc 路徑
$pandocPath = "C:\Program Files\Pandoc"
$newPath = "$currentPath;$pandocPath"

# 更新 PATH（需要管理員權限才能改系統變數）
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")

# 讓目前的 PowerShell 也能用
$env:Path = "$env:Path;$pandocPath"

# 測試
pandoc --version
            

注意：設定後可能需要重啟 PowerShell 才會生效

問題 2：pdflatex not found

錯誤訊息

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

原因

轉換 PDF 需要 LaTeX，但系統未安裝

解決方案

方案 A：安裝 MiKTeX（推薦，約 200MB）
方案 B：安裝 TeX Live（完整，約 5GB）
方案 C：不用 LaTeX，改用其他方式產生 PDF

安裝 MiKTeX

1前往 miktex.org

2下載 Windows 安裝檔

3執行安裝，選擇「為所有使用者安裝」

4設定自動安裝缺少的套件

小技巧：第一次轉換中文 PDF 可能需要下載字型，請耐心等待

不用 LaTeX 產生 PDF

方案 1：使用 wkhtmltopdf

                # 安裝 wkhtmltopdf 後
pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf
            

方案 2：先轉 HTML 再印成 PDF

                # 轉成 HTML
pandoc input.md -o output.html --standalone

# 用瀏覽器開啟 → 列印 → 存成 PDF
            

方案 3：先轉 Word 再存 PDF

                pandoc input.md -o output.docx
# 用 Word 開啟 → 另存新檔 → PDF
            

問題 3：無法執行腳本

錯誤訊息

無法載入檔案 .\script.ps1，因為這個系統上已停用指令碼執行。

原因

Windows 預設禁止執行 PowerShell 腳本（安全考量）

解決方法

                    # 以管理員身份開啟 PowerShell，執行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 或只允許目前會話
Set-ExecutionPolicy Bypass -Scope Process
                

執行原則說明

原則	說明
Restricted	禁止所有腳本（預設）
RemoteSigned	本機腳本可執行，下載的需簽署
Unrestricted	全部可執行（會警告）
Bypass	完全不檢查

建議：使用 RemoteSigned，兼顧安全和方便

問題 4：Pandoc 版本太舊

檢查版本

                pandoc --version
# 輸出: pandoc 3.1.x
            

為什麼要更新？

新版本支援更多格式
修復舊版本的 bug
效能改進
新功能（如 Lua 過濾器改進）

更新方法

從官網下載最新版重新安裝，會自動覆蓋舊版

環境檢查腳本

                # check-env.ps1
Write-Host "=== 環境檢查 ===" -ForegroundColor Cyan

# 1. Pandoc
Write-Host "`n[Pandoc]" -ForegroundColor Yellow
try {
    $v = pandoc --version | Select-Object -First 1
    Write-Host "  版本: $v" -ForegroundColor Green
} catch {
    Write-Host "  未安裝!" -ForegroundColor Red
}

# 2. LaTeX
Write-Host "`n[LaTeX]" -ForegroundColor Yellow
$latex = Get-Command pdflatex -ErrorAction SilentlyContinue
if ($latex) {
    Write-Host "  已安裝: $($latex.Source)" -ForegroundColor Green
} else {
    Write-Host "  未安裝 (PDF 轉換會受限)" -ForegroundColor Yellow
}

# 3. 執行原則
Write-Host "`n[執行原則]" -ForegroundColor Yellow
$policy = Get-ExecutionPolicy
Write-Host "  目前: $policy"

# 4. PATH
Write-Host "`n[PATH 檢查]" -ForegroundColor Yellow
$path = $env:Path -split ";"
$pandocInPath = $path | Where-Object { $_ -like "*pandoc*" }
if ($pandocInPath) {
    Write-Host "  Pandoc 在 PATH 中" -ForegroundColor Green
}
            

Antigravity 環境設定

確認 Antigravity 可以找到 Pandoc

                # 在 Antigravity 終端機中執行
pandoc --version
            

如果找不到，可能需要：

重啟 Antigravity（讓它讀取新的 PATH）
在 Antigravity 設定中指定 Pandoc 路徑
使用完整路徑執行 Pandoc

                # 使用完整路徑
& "C:\Program Files\Pandoc\pandoc.exe" input.md -o output.docx
            

Pandoc 相關環境變數

變數名稱	用途
PANDOC_DATA_DIR	自訂資料目錄（模板等）
LANG	語系設定（影響日期格式等）
HOME	使用者目錄

                # 查看 Pandoc 資料目錄
pandoc --version
# 輸出中會顯示 User data directory
            

實作練習

任務：檢查並修復環境

1執行 pandoc --version 確認安裝

2檢查 PowerShell 執行原則

3（選做）安裝 MiKTeX 支援 PDF

4建立環境檢查腳本

用 AI 協助環境設定

在 Antigravity 中提問

                我在 Windows 11 上安裝了 Pandoc，
但在 PowerShell 中執行 pandoc 時顯示找不到命令。
請幫我一步一步解決這個問題。
            

                我想要用 Pandoc 轉換 PDF，
但出現 pdflatex not found 錯誤。
請問最簡單的解決方法是什麼？
            

備份你的環境設定

                # 匯出環境變數
Get-ChildItem env: | Export-Csv "env-backup.csv" -NoTypeInformation

# 匯出 PATH
$env:Path -split ";" | Out-File "path-backup.txt"

# 匯出 PowerShell 設定
Get-ExecutionPolicy -List | Out-File "policy-backup.txt"
            

好處：重灌系統或換電腦時，可以快速恢復設定

小測驗

要讓 PowerShell 可以執行本機腳本，建議設定的執行原則是？

本單元總結

                學到的技巧
                檢查和安裝 Pandoc
設定 PATH 環境變數
安裝 LaTeX 支援 PDF 轉換
設定 PowerShell 執行原則
建立環境檢查腳本

            

下一步：在 Unit 03 學習如何用 AI 協助解決各種問題