寫這篇教程的起因很簡單我身邊好幾個朋友被畢業(yè)論文的排版逼到崩潰Word里調(diào)個公式能調(diào)半小時。我每次都跟他們說換LaTeX吧一勞永逸。但問題來了Mac用戶和Windows用戶問的第一句話往往不一樣Mac上裝MacTeX還是BasicTeXWindows上Texlive怎么下才不被龜速折磨裝好之后配VS Code還是Texstudio說實話我第一次從零搭環(huán)境的時候也被這些選擇搞得頭暈。這篇文章就把我實際踩過的坑、試過的方案全部攤開來講。從Mac和Windows雙平臺的下載安裝到VS Code和Texstudio的完整配置再到中文支持、語法入門、常見報錯排查一步不落都寫清楚。不管你是完全沒接觸過LaTeX的純小白還是被環(huán)境問題卡住的老手都可以照著一步步做下來。1. 內(nèi)容整體設(shè)計與思路拆解1.1 為什么LaTeX環(huán)境選擇這么重要LaTeX跟Word完全不同它本質(zhì)是一門排版語言你用純文本寫內(nèi)容編譯器負責(zé)把內(nèi)容渲染成精美排版的PDF文件。這就意味著參與流程的可選組件特別多發(fā)行版MacTeX、Texlive、MikTeX、編輯器VS Code、Texstudio、編譯器pdfLaTeX、XeLaTeX、LuaLaTeX再加上各種宏包依賴。這些組件之間的版本兼容、路徑配置、環(huán)境變量任何一個環(huán)節(jié)出問題都會導(dǎo)致編譯失敗。我在實際幫人排查的過程中發(fā)現(xiàn)90%的LaTeX新手問題不是語法問題而是環(huán)境問題。比如Mac上裝完MacTeX之后PATH沒生效Windows上安裝Texlive時用戶名是中文導(dǎo)致編譯報錯VS Code里裝了LaTeX Workshop但沒裝LaTeX發(fā)行版這些都是重災(zāi)區(qū)。1.2 全鏈路工具鏈選型從發(fā)行版到編輯器的組合邏輯這套方案選型其實是圍繞三個核心訴求展開的下載速度快、配置成本低、中文支持好。在Mac這一側(cè)我直接選MacTeX完整版。它的安裝包大約4GB多確實有點大但它內(nèi)置了TeX Live Manager、TeXShop、完整宏包集合裝完就能在終端里全局調(diào)用latexmk、xelatex等命令不需要再折騰任何依賴。對于大多數(shù)用戶來說省心比省空間更重要。當(dāng)然如果你硬要給Mac減負BasicTeX 手動裝ctex宏包的方案也可行但我不建議新手這么搞宏包依賴會把你折磨到懷疑人生。Windows這一側(cè)我從TUG官網(wǎng)和清華鏡像對比來看清華鏡像的Texlive下載速度通常在10MB/s以上而官網(wǎng)幾乎是幾百KB甚至幾十KB的龜速。所以Windows這邊我建議下載ISO鏡像后掛載安裝順帶把“從鏡像安裝”這項勾上后面補宏包就不需要重新下載整個發(fā)行版。編輯器選型上VS Code和Texstudio我都實際用了一段時間各自的定位其實很清楚VS Code是通用代碼編輯器在LaTeX方面靠LaTeX Workshop插件工作勝在插件生態(tài)豐富、主題UI自由定制、Git集成順手適合有一定開發(fā)習(xí)慣或者想統(tǒng)一編輯器的人Texstudio是專業(yè)LaTeX IDE開箱即用自帶結(jié)構(gòu)導(dǎo)航、公式編輯器、拼寫檢查非常適合完全沒寫過代碼的人。這個方案里我把兩條路的配置都寫出來你想走哪條自己挑。1.3 整體流程邏輯預(yù)覽在進入具體步驟之前先給你吃一顆定心丸。整個部署流程是拿到TeX發(fā)行版→安裝到系統(tǒng)里→配置編輯器指向編譯器→寫第一個文檔→編譯通過→按需擴展宏包和工具。整個過程下來Mac端順利的話20分鐘Windows端順利的話30分鐘左右。遇到鏡像速度極慢或者中文環(huán)境變量報錯這種特殊情況多花10分鐘也能解決。2. 核心細節(jié)解析與實操要點2.1 MacTeX安裝部署全步驟Mac上的安裝流程相對清爽但有幾個細節(jié)非常影響成敗。打開終端先確認你的Mac芯片架構(gòu)。命令是uname -m輸出結(jié)果是arm64就是Apple SiliconM系列芯片輸出x86_64就是Intel芯片。這一步?jīng)Q定了你下載哪個構(gòu)建版本。MacTeX官方對Apple Silicon提供了arm64版的.pkg安裝包Intel Mac用x86_64版即可。如果你在Intel Mac上裝了arm64包會直接提示“無法打開因為它來自身份不明的開發(fā)者”。然后打開MacTeX官網(wǎng)的下載頁找到MacTeX.pkg下載鏈接。完整版大約4-5GB下載時間取決于網(wǎng)速。為了繞開網(wǎng)絡(luò)不穩(wěn)定帶來的下載中斷我建議用支持斷點續(xù)傳的下載工具。下載完成后雙擊.pkg安裝包一路點擊“繼續(xù)”。安裝過程大約5到10分鐘。安裝完成后MacTeX默認把可執(zhí)行文件放在/Library/TeX/texbin/目錄下。但macOS不會自動把這個目錄加進PATH所以你需要手動配置# 打開shell配置文件如果你用zsh就編輯.zshrc用bash就編輯.bash_profile nano ~/.zshrc # 在文件末尾追加一行 export PATH/Library/TeX/texbin:$PATH # 保存退出后執(zhí)行 source ~/.zshrc驗證是否安裝成功latex --version xelatex --version latexmk --version這三條命令都能正常輸出版本號說明你的LaTeX環(huán)境已經(jīng)可以用了。注意macOS的Gatekeeper可能會攔截未簽名或未公證的軟件包如果雙擊安裝包時提示“已損壞”或“無法打開”可以右擊安裝包選擇“打開”或者到“系統(tǒng)設(shè)置→隱私與安全性”里點擊“仍要打開”實測大部分情況下這樣做可以順利裝完。2.2 Windows Texlive鏡像下載與安裝全步驟Windows這套流程我?guī)湍惆选翱印北艿妹髅靼装?。首先是下載。打開清華開源軟件鏡像站找到texlive目錄選擇最新的ISO文件下載目前主流的版本是TeX Live 2024或2025的ISO。鏡像里這個ISO差不多4GB左右。不建議去官網(wǎng)下install-tl.zip雖然也能裝但網(wǎng)絡(luò)不穩(wěn)定時經(jīng)常斷流。下載完成后不用解壓ISO直接在文件資源管理器里右鍵ISO文件選擇“裝載”會生成一個虛擬光驅(qū)盤符。打開它找到install-tl-windows.bat右鍵以管理員身份運行。這里有幾個選項一定要注意安裝方案選擇full也就是完整安裝避免以后缺宏包。省那點空間對你沒意義在寫論文的時候缺宏包報錯才真的讓你頭疼。安裝路徑建議保持默認的C:\texlive\2025。如果你執(zhí)意裝D盤可以從Advanced里修改TEXDIR路徑。最重要的一點如果Windows用戶名是中文比如C:\Users\張三請務(wù)必勾選No admin模式如果你只是當(dāng)前用戶安裝或者改到純英文目錄下安裝。中文用戶名導(dǎo)致的問題是TeX Live安裝過程中生成的各種臨時文件和路徑拼接時會編碼失敗而且CJK相關(guān)宏包在編譯時讀不到正確路徑。這個坑我?guī)腿齻€用戶排查過全是用戶名中文導(dǎo)致。安裝時間大約20-40分鐘取決于機器性能。裝完后打開cmd輸入tex --version xelatex --version能輸出版本號就說明安裝成功PATH也已經(jīng)被安裝包自動配置好了。2.3 VS Code安裝與LaTeX Workshop配置VS Code這邊先從官網(wǎng)下載macOS或者Windows對應(yīng)版本安裝。裝好后打開擴展商店搜索“LaTeX Workshop”插件點擊安裝它瞬間就能裝好。接下來需要改配置文件實現(xiàn)完整的中文支持。按Cmd,(Mac)或Ctrl,(Windows)打開設(shè)置面板點擊右上角的“打開設(shè)置(JSON)”圖標。在settings.json中加入如下內(nèi)容{ // 確保使用XeLaTeX編譯XeLaTeX是支持中文字體的引擎 latex-workshop.latex.recipes: [ { name: xelatex, tools: [ xelatex ] }, { name: xe-bib-xe-xe, tools: [ xelatex, bibtex, xelatex, xelatex ] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, %DOC% ] }, { name: bibtex, command: bibtex, args: [ %DOCFILE% ] } ], // 自動編譯開關(guān) latex-workshop.latex.autoBuild.run: onSave, // 編譯后自動清理輔助文件 latex-workshop.latex.clean.fileTypes: [ *.aux, *.log, *.fls, *.out, *.synctex.gz, *.bcf, *.run.xml, *.blg, *.bbl ], // 內(nèi)部查看PDF latex-workshop.view.pdf.viewer: tab }這里的關(guān)鍵是直接指定編譯器為xelatex而不是默認的pdflatex。原因很簡單pdfLaTeX對中文字體的處理需要額外配置XeLaTeX直接調(diào)用系統(tǒng)字體一句\usepackage{ctex}就能解決中文排版。注意有個細節(jié)-interactionnonstopmode參數(shù)的意義是遇到錯誤不暫停等待輸入而是直接報錯退出。這樣在VS Code里錯誤信息能直接在面板下方顯示出來定位問題效率高很多。配置完成后新建一個.tex文件點右上角的?按鈕如果彈出預(yù)覽窗口并且PDF渲染出來了就說明配置鏈路已經(jīng)打通。2.4 Texstudio安裝與中文配置Texstudio的安裝路徑相對簡單。從texstudio.sourceforge.net下載對應(yīng)的系統(tǒng)安裝包Windows下是.exe安裝程序Mac下是.dmg。安裝完成后打開Texstudio先不要急著寫代碼直接到“選項→設(shè)置Texstudio”里改幾個配置“構(gòu)建”選項卡默認編譯器改為XeLaTeX默認文獻工具改為BibTeX?！熬庉嬈鳌边x項卡勾選“行號”和“語法高亮”字體改成Source Code Pro或者Consolas中文顯示會好看很多。然后解決中文支持問題。Texstudio的界面本身是英文的但可以通過安裝中文語言包變成中文界面。Windows版的Texstudio在安裝目錄下自帶translations文件夾里面包含zh_CN.qm文件在“選項→設(shè)置Texstudio→常規(guī)→語言(需要重啟)”里選擇zh_CN重啟后界面就是中文了。真正需要注意的是中文拼寫檢查。Texstudio默認只帶英文詞典所以你在中文文檔里寫英文單詞可能老是看到紅色波浪線。你需要去下載dict目錄下的中文詞典文件zh_CN.dict和zh_CN.aff然后放到Texstudio的dict文件夾中再到“選項→設(shè)置Texstudio→編輯器→拼寫檢查詞典”里選擇簡體中文。這個步驟不做也不影響編譯但做了之后寫作體驗會提升一大截。3. 實操過程與核心環(huán)節(jié)實現(xiàn)3.1 第一個完整LaTeX文檔從建文件到編譯出PDF環(huán)境都裝好后最重要的就是親手跑通一個完整的文檔流程。我建議不要直接從空文檔開始最好用下面這個兼具體驗和實用性的模板打底。以VS Code為例新建一個文件夾叫l(wèi)atex_first在里面新建main.tex文件寫入\documentclass[12pt]{article} % 引入中文支持宏包 \usepackage[UTF8]{ctex} % 頁面設(shè)置 \usepackage[a4paper, margin2.5cm]{geometry} % 超鏈接支持 \usepackage{hyperref} \title{我的第一個LaTeX文檔} \author{你的名字} \date{\today} \begin{document} \maketitle \section{為什么選擇LaTeX} LaTeX是一種基于TeX的排版系統(tǒng)尤其適合處理數(shù)學(xué)公式、科技論文和學(xué)術(shù)報告。它最大的優(yōu)勢是內(nèi)容和樣式分離你只需要關(guān)注寫作內(nèi)容排版交給編譯器。 \section{數(shù)學(xué)公式} 行內(nèi)公式示例$Emc^2$。 獨立公式使用equation環(huán)境 \begin{equation} \int_{-\infty}^{\infty} e^{-x^2} \, dx \sqrt{\pi} \label{eq:gaussian} \end{equation} \section{插入圖片} 圖片需要提前把文件放在同目錄下然后使用 \begin{verbatim} \includegraphics[width0.8\textwidth]{example.png} \end{verbatim} \section{超鏈接} 訪問 \href{https://www.tug.org}{TeX Users Group} 了解更多信息。 \end{document}在VS Code里保存文件后因為前面設(shè)置了onSave自動編譯所以左側(cè)的操作流程是保存文件→右下角狀態(tài)欄出現(xiàn)編譯圖標→編譯完成后右側(cè)預(yù)覽窗口自動彈出PDF。如果是Texstudio點擊“工具→構(gòu)建并查看”即可。我自己第一次編譯時經(jīng)歷過幾秒鐘的“恐慌等待”因為終端刷了一堆日志實際上那是正常的宏包加載過程。只要最終退出碼是0并且PDF正常渲染就沒問題。3.2 LaTeX核心語法快速上手環(huán)境通了之后接下來就是學(xué)語法。我講課的習(xí)慣是先讓你掌握一個最小閉環(huán)文檔結(jié)構(gòu)-段落與標題-列表-圖片表格-數(shù)學(xué)公式。這幾樣覆蓋了絕大多數(shù)日常需求。文檔結(jié)構(gòu)以\documentclass{}開頭正文放在\begin{document}和\end{document}之間其他都是導(dǎo)言區(qū)。段落與標題內(nèi)容之間留一個空行就是另起一段\section{}、\subsection{}、\subsubsection{}控制章節(jié)層級。列表無序列表用itemize環(huán)境有序列表用enumerate環(huán)境每一項用\item開頭。圖片導(dǎo)言區(qū)加載graphicx宏包正文用\includegraphics[width0.5\textwidth]{文件名}。注意圖片文件名不能含中文否則XeLaTeX在部分環(huán)境下會找不到文件這是我在Windows上踩過的坑。表格用tabular環(huán)境|c|c|表示兩列居中并帶豎線\hline表示水平線。如果你想讓長表格跨頁自動斷行需要引入longtable宏包。數(shù)學(xué)公式行內(nèi)公式用$...$獨立公式用equation環(huán)境。上下標分別用^和_分數(shù)用\frac{分子}{分母}。這些基礎(chǔ)符號記得住就行。3.3 中文字體與換行符細節(jié)中文用戶最關(guān)心的問題是字體。ctex宏包默認選擇系統(tǒng)自帶的中文字體Windows上是中易系列Mac上是蘋方和宋體。如果你對字體不滿意可以顯式指定\usepackage[UTF8, fontsetmacnew]{ctex}Mac上這個設(shè)置會調(diào)用“宋體-簡”和“蘋方”。Windows上可以試試fontsetwindows來用微軟雅黑和宋體。如果你的論文模板對字體有硬性要求這一步很關(guān)鍵。關(guān)于換行符LaTeX里很多人不知道怎么寫。如果你在源文件里直接回車編譯出來在PDF里是不分段的。正確的做法有兩種段落間插一個空行這是段落分隔。強制換行用\\或\newline。但要注意\\在正文里也可以用不過如果后面緊跟\begin{equation}之類的環(huán)境編譯可能會報警告。這種情況建議用\par?？傊诙闻c段之間留空行是LaTeX最推薦、最不容易出問題的習(xí)慣。4. 常見問題與排查技巧實錄4.1 中文用戶名導(dǎo)致Texlive安裝失敗這個問題多發(fā)生在Windows上。如果用戶名是中文比如登錄的是C:\Users\張三在安裝Texlive時install-tl-windows.bat會使用當(dāng)前用戶的臨時目錄存放解壓文件而系統(tǒng)臨時目錄路徑同樣包含中文。最終表現(xiàn)可能是解壓過程報錯或者安裝完成后編譯時找不到latex.exe。我當(dāng)時幫一個朋友排查xelatex main.tex一直報“系統(tǒng)找不到指定的路徑”。挨個檢查PATH、檢查防火墻、檢查殺毒軟件最后發(fā)現(xiàn)根源就是中文用戶名。解決辦法是新建一個英文名管理員賬戶在這個賬戶下完成安裝和編譯。如果你不想新建賬戶可以試試以管理員身份把TEXDIR和用戶臨時目錄都改成純英文路徑讓中文用戶名不再參與路徑拼接。但這個方法不是100%穩(wěn)能用英文賬戶就別折騰。4.2 MacTeX安裝后終端找不到命令MacTeX的GUI安裝包安裝完成后終端如果還是提示command not found: latex基本可以斷定是PATH沒有配置好。很多新手會順手把命令寫成export PATH/Library/TeX/texbin:$PATH看起來沒問題但如果你用的shell是zsh它不讀.bash_profile所以必須寫進.zshrc。另外一個容易踩的隱藏坑如果你提前安裝了跨平臺包管理器Homebrew它會強制把shell切換到zsh但你的.zshrc文件還沒創(chuàng)建。這時候不要慌先執(zhí)行touch ~/.zshrc創(chuàng)建文件再寫入PATH配置。4.3 LaTeX編譯報錯時怎么看log定位問題新手一看到大段紅色報錯就發(fā)慌其實LaTeX的報錯定位邏輯非常清晰。VS Code的LaTeX Workshop面板下方會直接顯示錯誤信息Texstudio也有“消息”面板。真正有用的信息往往不是那句紅字而是log文件里的具體行號。當(dāng)我們用-file-line-error參數(shù)編譯時報錯會帶文件名和行號/path/to/main.tex:12: Undefined control sequence. \usepackage意思就是main.tex第12行有一個未定義的命令。多數(shù)情況下報錯原因就三類宏包名拼錯了比如graphic少寫了x。某宏包沒安裝比如\usepackage{somepkg}但發(fā)行版里沒有這個宏包。大括號沒閉合比如\textbf{This is bold text}漏了右括號后面的內(nèi)容全部被錯誤地變成了粗體并且報“Paragraph ended before \textbf was complete”。如果log文件末尾出現(xiàn)“Emergency stop”通常是文檔結(jié)構(gòu)破損嚴重像\begin{document}和\end{document}數(shù)量不匹配。這時逐個檢查環(huán)境配對即可。4.4 常見問題速查表現(xiàn)象可能原因解決方案安裝Texlive后命令行找不到命令未重啟終端或未配置PATH重啟終端檢查環(huán)境變量是否包含texlive路徑VS Code編譯按鈕灰色未安裝LaTeX Workshop插件或未打開.tex文件安裝插件后重新加載窗口確認文件擴展名是.tex編譯報錯“Undefined control sequence”宏包名拼錯或未引入宏包根據(jù)行號定位檢查宏包名和花括號配對中文字體顯示為方塊未使用XeLaTeX或ctex宏包編譯器改為XeLaTeX文檔中加入\usepackage{ctex}Windows安裝過程中途失敗殺毒軟件攔截或臨時目錄含中文暫時退出安全軟件使用純英文臨時目錄表格內(nèi)容超出頁面寬度列寬未限制或內(nèi)容過長使用p{寬度}列類型定義列寬或用tabularx宏包自動換行PDF中鏈接無法跳轉(zhuǎn)未加載hyperref宏包導(dǎo)言區(qū)加\usepackage{hyperref}4.5 雙編輯器共存的使用心得有的讀者可能糾結(jié)VS Code和Texstudio到底選哪個其實這倆可以共存同時裝沒問題因為你電腦上真正干活的是LaTeX發(fā)行版編輯器只是前端外殼。我在Mac上主力VS Code因為看代碼、寫博客、寫LaTeX都在同一個編輯器里不用來回切換。但在Windows上反而喜歡Texstudio因為項目里中文用戶多Texstudio對BibTeX條目也有可視化的摘要對于頻繁改參考文獻的論文黨更順手。實用建議是第一周先嚴格用某一個編輯器把發(fā)布文檔完整跑通兩三次再切到另一個感受一下。不要第一天就反復(fù)橫跳那樣會混淆工具差異和自身操作問題。5. 從入門到順手幾個提升效率的進階操作5.1 用模板管理論文格式實際寫論文時最痛苦的往往不是語法而是學(xué)校給的Word模板和LaTeX的對應(yīng)。國內(nèi)大多數(shù)高校都已經(jīng)有開源的LaTeX學(xué)位論文模板比如清華的thuthesis、上海交大的sjtuthesis、中科大的ustcthesisGitHub上都可以找到。你可以fork一份到本地把main.tex里的個人信息、標題、摘要替換成自己的即可。模板的使用核心就三點第一確認模板推薦的編譯方式一般是XeLaTeX極少數(shù)老模板還在用pdfLaTeX;第二確認模板依賴的宏包是否已經(jīng)安裝缺哪個就打開TeX Live Manager勾選哪個第三不要隨意改動模板的cls文件和sty文件除非你真的懂。5.2 使用SyncTeX實現(xiàn)反向定位寫長文檔時最煩的就是在PDF里看到一行錯位要回源碼改找不到位置。SyncTeX就是解決這個問題的編譯時開啟-synctex1VS Code里按住Cmd點擊Mac或Ctrl點擊WindowsPDF預(yù)覽的任意位置就能跳到源碼里對應(yīng)的那一行。反向也一樣在源碼里按住Cmd點擊跳轉(zhuǎn)到PDF對應(yīng)位置。Texstudio里默認快捷鍵是Cmd點擊或F7。這個功能平時不顯眼但寫100頁以上論文時能省掉肉眼找行的痛苦強烈建議熟練使用。5.3 LaTeX報錯恐慌自救指南我見過太多新手一看到紅色報錯就怕怕編譯器把文檔弄壞了。實際上LaTeX編譯非常安全——它只是執(zhí)行一次純文本處理把你的.tex源文件轉(zhuǎn)換成PDF最多生成一些.aux、.log之類的輔助文件不會傷害源文件。所以你大可以放心去改、去試、去折騰。萬一改到編都編不過去最粗暴有效的辦法是把最近一次能正常編譯的.tex文件備份一份再繼續(xù)改。這種“版本回滾”思路跟開發(fā)里用Git一樣只不過我們手動操作而已。等哪一天你熟練了再去研究.git管理LaTeX項目也不遲。在M1/M2芯片的Mac上如果你用Texstudio遇到界面模糊的問題可以在“顯示簡介→勾選使用Rosetta打開”里解決這是Intel版本在Apple Silicon上的兼容層模式實測能修復(fù)渲染問題。Windows上如果TeX Live安裝到一半提示某個包校驗失敗不用全部重來直接再次運行安裝腳本它會跳過已經(jīng)裝好的包繼續(xù)安裝。這些環(huán)境搭建的細節(jié)沒有哪一條是書本上會認真教你的全是我一遍一遍試出來的。今天一次性全寫出來就是希望你能繞開這些明坑暗坑把時間花在真正重要的事情上——寫出高質(zhì)量的論文或文檔。環(huán)境只是起點順暢跑通之后盡情享受LaTeX帶來的極致排版體驗就好。