在 Mac 上以 VS Code 編輯 LaTeX

本文基於以下幾篇文章完成，由於我只需要 Paper 和 Book 兩種版型所以省略了很多步驟，如果需要完整版教學的請看原文：

本文只說明 MacOS 的安裝方式，Windows 系統通常是用 Docker 模擬 Linux 環境以完成本地編輯，做法請見以下三篇教學文章

沒想到這篇文章會是本站點擊 Top 3 的文章，因此於 2025/11 特地回來更新文章。

應該本地編輯還是使用 Overleaf？

請先衡量自己是否該在本地編輯 LaTeX 或是直接用免費的 Overleaf 編輯，需要考慮的有三大因素：編譯時間、程式容量以及錯誤處理。

編譯時間

編譯時間以我的情境為範例提供讀者參考。我使用包含 tikz 套件，並且文章內插入其他 PDF 圖片以及文件，文中總長度約 70 頁 A4，在 M1 Mac 上面進行測試：

本地編譯耗時約 7.5 秒，Overleaf 編譯時間約 10 秒
在 Overleaf 會經常警告編譯超時，約有 2% 機率編譯失敗需要重新編譯

因此如果電腦比 M1 爛可以考慮直接在 Overleaf 上編譯，當頁數更多或者套件內容更複雜時就可以考慮本地編譯。

容量問題

在容量寸土寸金的 Mac 上 MacTeX 需要 6GB 的儲存空間，Windows 就無此困擾。

錯誤處理

Overleaf 幫你處理了常見問題，如 build command, 字體等等，這些問題在本地需要自行解決，不過都要寫 LaTeX 了我想大家都有基本的除錯能力。

安裝教學

前面我們分析了是否應該在本地編譯，看到這裡就表示你的答案是 yes。這個章節會說明如何安裝，總共需要安裝這些工具才能在 Mac 上編譯 LaTeX：

brew 套件管理器
MacTeX，LaTeX 本身
VS Code，文字編輯器，因為 MacTeX 編輯器醜到不行
VS Code 的 LaTeX 插件 LaTeX Workshop
安裝標楷體

安裝 Brew

先安裝套件管理器，後續所有安裝都使用此管理器。

# 安裝
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 刷新 shell
exec zsh

# 檢查
brew --version

# 如果沒有找到 brew，需要把 brew 加入系統路徑
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc

# 再次刷新 shell
exec zsh

網路教學會把「加入系統路徑的指令」改為 echo 'eval $(/opt/homebrew/bin/brew shellenv)' >> ~/.zprofile，兩者差別為前者只會加入系統路徑，後者除了系統路徑還會加上補全系統，這會導致終端機啟動速度變慢，依照個人需求選擇。

安裝 LaTeX

MacTeX 容量 6GB，他的伺服器網速又很慢，安裝時可以先去滑手機。

# 安裝 MacTeX
brew install --cask MacTeX-no-gui

# 安裝完成後重新開啟終端機

# 更新 LaTeX packages
sudo tlmgr update --self
sudo tlmgr update --all

安裝 VS Code

只需要一行就可完成。

brew install --cask visual-studio-code

如果不想用 Brew 安裝 VS Code 也可以到官網手動安裝。

安裝 VS Code LaTeX 插件

點擊此連結安裝 LaTeX Workshop。

安裝標楷體

Windows 和 Mac 的標楷體雖然名稱一樣但是顯示效果不一樣，他們只有名稱相同因此換到 Windows 開就一定會跑版，解決方法是找到 Windows 的 ttf 檔案替換，怎麼做請自行解決，這裡不介紹違法方式。

設定

前面介紹完安裝，但是安裝後還要設定才能使用，這些設定包含 Mac 一定會遇到的標楷體問題。

設定 LaTeX 編譯

複製以下文本

Preferences: Open User Settings (JSON)

打開 VS Code，按下 command + shift + p，貼上剛才複製的文本，enter 開啟設定檔 JSON 文件。
貼上設定檔

{
    "LaTeX-workshop.LaTeX.tools": [
    {
      "name": "xeLaTeX",
      "command": "/Library/TeX/TeXbin/xeLaTeX",
      "args": [
        "-syncTeX=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
      ]
    },
    {
      "name": "bibTeX",
      "command": "/Library/TeX/TeXbin/bibTeX",
      "args": [
        "%DOCFILE%"
      ]
    },
    {
      "name": "LaTeXmk-xeLaTeX",
      "command": "/Library/TeX/TeXbin/LaTeXmk",
      "args": [
        "-xeLaTeX",
        "-syncTeX=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ]
    }
  ],
  "LaTeX-workshop.LaTeX.recipes": [
    {
      "name": "XeLaTeX ➞ bibTeX ➞ XeLaTeX×2",
      "tools": [
        "xeLaTeX",
        "bibTeX",
        "xeLaTeX",
        "xeLaTeX"
      ]
    },
    {
      "name": "LaTeXmk 🔃",
      "tools": [
        "LaTeXmk-xeLaTeX"
      ]
    }
  ],
  "LaTeX-workshop.view.pdf.viewer": "tab",
  "LaTeX-workshop.LaTeX.autoBuild.run": "onSave",
  "LaTeX-workshop.LaTeX.autoClean.run": "onFailed",
  "LaTeX-workshop.LaTeX.clean.fileTypes": [
    "*.aux",
    "*.bbl",
    "*.blg",
    "*.idx",
    "*.ind",
    "*.lof",
    "*.lot",
    "*.out",
    "*.toc",
    "*.acn",
    "*.acr",
    "*.alg",
    "*.glg",
    "*.glo",
    "*.gls",
    "*.fls",
    "*.log",
    "*.fdb_LaTeXmk",
    "*.snm",
    "*.syncTeX(busy)",
    "*.syncTeX.gz(busy)",
    "*.nav"
  ],
  "LaTeX-workshop.LaTeX.recipe.default": "lastUsed",
  "LaTeX-workshop.view.pdf.internal.syncTeX.keybinding": "double-click",
  "editor.unicodeHighlight.allowedLocales": {
    "zh-hans": true,
    "zh-hant": true
  },
  "[LaTeX]": {
    "editor.defaultFormatter": "James-Yu.LaTeX-workshop"
  }
}

其中 LaTeX-workshop.LaTeX.recipes 是目錄，編譯時可以選擇使用哪個 recipe 編譯，而 LaTeX-workshop.LaTeX.tools 代表的是該 recipe 執行的具體方式。

完整版本請見科研必会——在Mac上配置LaTeX写作环境，我用不到那麼多所以只留下必要的，兩個 recipe 分別代表

XeLaTeX ➞ bibTeX ➞ XeLaTeX×2: 傳統編譯方式，需要先編譯 XeLaTeX，再回來編 bibTeX，最後又要整合，耗時約 20 秒，比 Overleaf 更慢。
LaTeXmk: 整合上述步驟，執行時間只需要 7.5 秒。

設定字體

這是我在 Overleaf 的設定，直接把 BiauKai.ttf 上傳到 Overleaf 專案根目錄就可以直接套用字體：

\setCJKmainfont[AutoFakeBold=6,AutoFakeSlant=.4]{[BiauKai.ttf]}
\defaultCJKfontfeatures{AutoFakeBold=6,AutoFakeSlant=.4}
\newCJKfontfamily\Kai{[BiauKai.ttf]}        %定義指令\Kai則切換成標楷體

改為本地編譯後原本的方法就行不通了，修正方式是改用系統的 ttf 檔案，tex 檔案的設定改為以下：

\setCJKmainfont[AutoFakeBold=6,AutoFakeSlant=.4]{DFKai-SB}
\defaultCJKfontfeatures{AutoFakeBold=6,AutoFakeSlant=.4}
\newCJKfontfamily\Kai{DFKai-SB}

DFKai-SB 代表「ttf 設定的字體名稱」，這是 ttf 設定的和檔案名稱不一樣，你可以使用以下指令檢查字體檔的字體名稱是否也是 DFKai-SB：

# 安裝字體套件
brew install fontconfig

# 檢查字體檔案
# 請把你的 ttf 檔案放在這個目錄系統才能偵測到
fc-list | grep "/Library/Fonts/kaiu.ttf"

# 輸出
>>> /Library/Fonts/kaiu.ttf: DFKai\-SB,標楷體:style=Regular

此輸出代表 DFKai-SB 和 標楷體 都是字體名稱。

設定 VS Code 換行

由於 LaTeX 一行都很長所以要設定自動換行 (wrap)，如果目錄中沒有 .vscode/settings.json，直接在終端機貼上

mkdir -p .vscode
cat > .vscode/settings.json <<EOF
{
  "editor.wordWrap": "on"
}
EOF

或者手動開啟文件加入

"editor.wordWrap": "on"

版本控制

經過前面那一長串的安裝和設定你現在終於可以在本地編輯 LaTeX 了，這裡筆者再額外引入一個版本控制的觀念。筆者強烈建議使用 Git 對你的文件進行版本控制，這是非常優秀的版本控制系統，即使你完全不會 Git，但是只要學會最基本的新增版本記錄都比不用來的好，這樣的好處是，未來某個版本出問題了，你再上網查怎麼回退就好了，因為每個版本都有記錄。

Git 版本控制通常只會記錄原始文件不記錄自動生成的文件，因為自動生成的文件每次編譯的結果都一樣因此不需浪費儲存空間記錄，我們可以在專案根目錄新增 .gitignore 設定忽略的檔案，以下是 LaTeX 專案的 .gitignore 設定檔：

.gitignore

來自 https://github.com/github/gitignore/blob/main/TeX.gitignore

## Core latex/pdflatex auxiliary files:
*.aux
*.lof
*.log
*.lot
*.fls
*.out
*.toc
*.fmt
*.fot
*.cb
*.cb2
.*.lb

## Intermediate documents:
*.dvi
*.xdv
*-converted-to.*
# these rules might exclude image files for figures etc.
# *.ps
# *.eps
# *.pdf

## Generated if empty string is given at "Please type another file name for output:"
.pdf

## Bibliography auxiliary files (bibtex/biblatex/biber):
*.bbl
*.bbl-SAVE-ERROR
*.bcf
*.bcf-SAVE-ERROR
*.blg
*-blx.aux
*-blx.bib
*.run.xml

## Build tool auxiliary files:
*.fdb_latexmk
*.synctex
*.synctex(busy)
*.synctex.gz
*.synctex.gz(busy)
*.pdfsync
*.rubbercache
rubber.cache

## Build tool directories for auxiliary files
# latexrun
latex.out/

## Auxiliary and intermediate files from other packages:
# algorithms
*.alg
*.loa

# achemso
acs-*.bib

# amsthm
*.thm

# attachfile2
*.atfi

# beamer
*.nav
*.pre
*.snm
*.vrb

# changes
*.soc
*.loc

# comment
*.cut

# cprotect
*.cpt

# elsarticle (documentclass of Elsevier journals)
*.spl

# endnotes
*.ent

# fixme
*.lox

# feynmf/feynmp
*.mf
*.mp
*.t[1-9]
*.t[1-9][0-9]
*.tfm

#(r)(e)ledmac/(r)(e)ledpar
*.end
*.?end
*.[1-9]
*.[1-9][0-9]
*.[1-9][0-9][0-9]
*.[1-9]R
*.[1-9][0-9]R
*.[1-9][0-9][0-9]R
*.eledsec[1-9]
*.eledsec[1-9]R
*.eledsec[1-9][0-9]
*.eledsec[1-9][0-9]R
*.eledsec[1-9][0-9][0-9]
*.eledsec[1-9][0-9][0-9]R

# glossaries
*.acn
*.acr
*.glg
*.glo
*.gls
*.glsdefs
*.lzo
*.lzs
*.slg
*.slo
*.sls

# uncomment this for glossaries-extra (will ignore makeindex's style files!)
# *.ist

# gnuplot
*.gnuplot
*.table

# gnuplottex
*-gnuplottex-*

# gregoriotex
*.gaux
*.glog
*.gtex

# htlatex
*.4ct
*.4tc
*.idv
*.lg
*.trc
*.xref

# hypdoc
*.hd

# hyperref
*.brf

# knitr
*-concordance.tex
# TODO Uncomment the next line if you use knitr and want to ignore its generated tikz files
# *.tikz
*-tikzDictionary

# listings
*.lol

# luatexja-ruby
*.ltjruby

# makeidx
*.idx
*.ilg
*.ind

# minitoc
*.maf
*.mlf
*.mlt
*.mtc[0-9]*
*.slf[0-9]*
*.slt[0-9]*
*.stc[0-9]*

# minted
_minted*
*.data.minted
*.pyg

# morewrites
*.mw

# newpax
*.newpax

# nomencl
*.nlg
*.nlo
*.nls

# pax
*.pax

# pdfpcnotes
*.pdfpc

# sagetex
*.sagetex.sage
*.sagetex.py
*.sagetex.scmd

# scrwfile
*.wrt

# svg
svg-inkscape/

# sympy
*.sout
*.sympy
sympy-plots-for-*.tex/

# pdfcomment
*.upa
*.upb

# pythontex
*.pytxcode
pythontex-files-*/

# tcolorbox
*.listing

# thmtools
*.loe

# TikZ & PGF
*.dpth
*.md5
*.auxlock

# titletoc
*.ptc

# todonotes
*.tdo

# vhistory
*.hst
*.ver

# easy-todo
*.lod

# xcolor
*.xcp

# xmpincl
*.xmpi

# xindy
*.xdy

# xypic precompiled matrices and outlines
*.xyc
*.xyd

# endfloat
*.ttt
*.fff

# Latexian
TSWLatexianTemp*

## Editors:
# WinEdt
*.bak
*.sav

# Texpad
.texpadtmp

# LyX
*.lyx~

# Kile
*.backup

# gummi
.*.swp

# KBibTeX
*~[0-9]*

# TeXnicCenter
*.tps

# auto folder when using emacs and auctex
./auto/*
*.el

# expex forward references with \gathertags
*-tags.tex

# standalone packages
*.sta

# Makeindex log files
*.lpz

# xwatermark package
*.xwm

# REVTeX puts footnotes in the bibliography by default, unless the nofootinbib
# option is specified. Footnotes are the stored in a file with suffix Notes.bib.
# Uncomment the next line to have this generated file ignored.
#*Notes.bib

協作

由於我不需要協作所以沒有用這個方案，請看原文 Syncing VSCode with Overleaf for Collaboration and Reviews。

FAQ

寫給我自己的常見問題，都是問 AI 的

TeX LaTeX kaTeX差在哪，繁體中文回答
- TeX 是底層語言，我們不會直接用他來寫文件，輸出格式為 DVI
- LaTeX 是基於 TeX 的巨集包，輸出格式還是 DVI
- KaTeX 是一種專為網頁設計的數學排版程式庫
LaTeX XeTeX XeLaTeX pdfTeX LuaTeX 差在哪
- LaTeX 與原始 TeX 一樣，對中文等非拉丁文字的支援有限
- pdfTeX 是 TeX 的改進版本，可直接輸出 PDF 檔案，也改進了字距調整和連字功能，但是字元支援仍然有限
- XeTeX 和 XeLaTeX
  - XeTeX 是現代 TeX 引擎
  - XeLaTeX 是使用 XeTeX 引擎的 LaTeX 格式
  - 原生支援 Unicode 和 UTF-8 編碼，非常適合中文等多語言排版
- LuaTeX 最新的 TeX 引擎，整合了 Lua 腳本語言，完全支援 Unicode 和 UTF-8 編碼
加速編譯
問 AI 只會給廢話，看起來比較有用的方式是
1. 指定字型，不要每次都搜尋整個系統
2. 分塊編譯，比如每次都只編譯特定 section 而不是整本書

應該本地編輯還是使用 Overleaf？​

編譯時間​

容量問題​

錯誤處理​

安裝教學​

安裝 Brew​

安裝 LaTeX​

安裝 VS Code​

安裝 VS Code LaTeX 插件​

安裝標楷體​

設定​

設定 LaTeX 編譯​

設定字體​

設定 VS Code 換行​

版本控制​

協作​

FAQ​