Visual Studio Code에 LaTeX Workshop 확장을 추가하면 범용 코드 편집기는 심각한 LaTeX 환경이 됩니다. 저장할 때마다 컴파일하고 PDF를 나란히 탭에 표시하며 소스와 PDF 사이를 양방향으로 이동할 수 있습니다. 이 페이지에서는 설정, 빌드 작동 방식(레시피 및 도구) 및 SyncTeX 통합을 안내합니다.
LaTeX Workshop가 무엇인가요?
VS Code는 TeX 자체를 조판하지 않습니다. 실제 컴파일은 컴퓨터에 설치한 배포판(TeX Live(또는 MiKTeX / MacTeX))에 의해 수행됩니다. James Yu가 작성한 LaTeX Workshop는 편집기와 해당 배포판 사이의 다리입니다. 빌드를 시작하고, PDF를 미리 보고, 완성, 구문 강조 표시, \ref/\cite에 대한 정의로 이동, 개요 보기 등을 추가합니다. 마켓플레이스 ID는 James-Yu.latex-workshop이며 500만 건 이상의 설치를 기록했습니다. 사실상 VS Code 생태계의 기본 LaTeX 확장입니다.
한 가지 전제 조건은 TeX 명령이 PATH에서 접근 가능하다는 것입니다. 확장은 단순히 latexmk 또는 pdflatex와 같은 실행 파일을 하위 프로세스로 생성하므로 latexmk --version가 터미널에서 작동하면 확장도 거의 확실하게 작동합니다. 반대로 엔진을 선택하거나 일본어 글꼴을 구성하는 것은 확장의 문제가 아니라 배포의 문제입니다.
먼저 터미널에서 한 번 컴파일하세요.
VS Code 설정을 조정하기 전에 터미널에서 동일한 프로젝트를 한 번 빌드하십시오. latexmk가 그곳에서 실행될 수 없으면 LaTeX Workshop도 실행할 수 없습니다. 첫 번째 문서의 경우 프로젝트 폴더에서 다음 중 하나를 시도해 보세요.
latexmk -pdf main.tex
# 日本語 upLaTeX を .latexmkrc に書いた場合 / if .latexmkrc selects upLaTeX
latexmk main.texPATH 및 패키지 누락 오류가 해결되면 모든 VS Code 측 오류는 레시피, 루트 파일 감지 또는 PDF 뷰어로 범위가 좁아집니다. 터미널 빌드는 작동하지만 확장이 실패하는 경우 settings.json를 검사하십시오. 출력 디렉터리, 레시피 이름 및 자리 표시자가 일반적인 용의자입니다.
설정
단계는 간단합니다. VS Code를 설치하고 TeX Live(2026년에는 TeX Live 2026)와 같은 배포판을 설치한 후 PATH에 있는지 확인하세요. 그런 다음 확장 보기(Ctrl/Cmd+Shift+X)를 열고 "LaTeX Workshop"를 검색하여 설치하십시오. PATH를 변경한 직후 VS Code(이상적으로는 전체 OS)를 다시 시작하여 새 환경을 선택합니다. .tex 파일을 열면 왼쪽의 TeX 활동 표시줄 아이콘을 통해 빌드 및 미리보기 명령이 제공됩니다.
Settings는 settings.json에 있습니다(Ctrl/Cmd+, Settings UI에서 오른쪽 상단의 "Open Settings(JSON)"를 사용합니다. 전역 사용자 파일 또는 프로젝트별 .vscode/settings.json를 편집할 수 있습니다). 먼저 알아야 할 세 가지 핵심은 다음과 같습니다.
latex-workshop.latex.outDir— 중간 파일과 PDF가 가는 곳. 기본%DIR%(.tex옆). 예를 들어 설정out는 소스 폴더를 깔끔하게 유지합니다.latex-workshop.latex.autoBuild.run— 자동 빌드를 트리거하는 요소:onFileChange(기본값, 종속성 감시),onSave(저장 시) 또는never(수동 전용). 예측 가능한 동작을 원한다면onSave가 안전한 선택입니다.latex-workshop.view.pdf.viewer— PDF가 나타나는 위치:tab(기본값, VS Code 내부 탭),browser또는external. 마찰이 없는 SyncTeX의 경우tab가 최선의 선택입니다.
최소한의 시작점은 다음과 같습니다. out/에서 출력을 수집하고, 저장 시 빌드하고, 내장 탭에 PDF를 표시합니다.
{
"latex-workshop.latex.outDir": "%DIR%/out",
"latex-workshop.latex.autoBuild.run": "onSave",
"latex-workshop.view.pdf.viewer": "tab"
}%DIR%는 처리 중인 루트 파일의 디렉터리로 확장되는 자리 표시자입니다. 아래 레시피에 다시 나타납니다. 빌드 후 확장 프로그램은 latex-workshop.latex.autoClean.run를 통해 중간 파일(.aux, .log, …)을 정리하거나 유지할 수도 있지만 출력 디렉터리와 트리거를 설정하는 것만으로도 느낌을 얻을 수 있습니다.
레시피 및 도구 구축
LaTeX Workshop의 빌드에는 “도구”와 “레시피”라는 두 개의 레이어가 있습니다. 도구(latex-workshop.latex.tools)는 실행할 단일 명령(name, command(실행 파일) 및 args)을 정의합니다. 레시피(latex-workshop.latex.recipes)는 도구 이름을 나열하는 name 및 tools 배열이 포함된 도구의 정렬된 시퀀스**입니다. "pdflatex → bibtex → pdflatex → pdflatex"(참고문헌 패스를 실행한 후 다시 실행)와 같은 흐름이 하나의 레시피로 표현됩니다.
구성이 없으면 확장 프로그램은 내장된 기본 레시피를 사용합니다. 첫 번째는 단독 latexmk이고 이것이 의도된 기본값입니다(latex-workshop.latex.recipe.default가 "first"인 경우 목록의 최상위 레시피가 선택됩니다. 마지막으로 선택한 레시피를 기억하려면 "lastUsed"로 설정하세요). latexmk는 종속성을 검사하고 필요한 만큼 정확하게 다시 실행하므로 상호 참조, 목차 또는 참고 문헌에 대한 패스를 계산할 필요가 없습니다. 기본 latexmk 도구는 대략 다음과 같이 정의됩니다.
{
"name": "latexmk",
"command": "latexmk",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"-pdf",
"-outdir=%OUTDIR%",
"%DOC%"
],
"env": {}
}인수 읽기: -synctex=1는 아래에 설명된 SyncTeX 데이터를 내보냅니다. -interaction=nonstopmode는 오류 발생 시 입력을 중단하는 대신 곧바로 실행됩니다. -file-line-error는 오류를 "file:line: message"로 인쇄하므로 문제가 있는 지점으로 쉽게 이동할 수 있습니다. -pdf는 latexmk에게 pdfLaTeX를 통해 직접 PDF를 생성하도록 지시합니다. %OUTDIR%는 outDir로 확장되고 %DOC%는 확장자가 없는 루트 파일 경로로 확장됩니다(다른 자리 표시자에는 %DOCFILE% = 확장자가 없는 파일 이름 및 %DIR% = 루트 디렉터리가 포함됩니다).
기본 레시피에는 엔진 변형 latexmk (lualatex) 및 latexmk (xelatex)와 추가 인수 없이 latexmk %DOC%를 실행하고 모든 것을 .latexmkrc로 연기하는 latexmk (latexmkrc)도 포함됩니다. 일본어의 경우 "모든 것을 .latexmkrc에 넣는" 접근 방식이 가장 깔끔합니다. 프로젝트 루트에 .latexmkrc를 삭제하고 엔진과 변환기의 이름을 지정합니다. 다음은 upLaTeX + dvipdfmx 설정입니다. 과학 분야 일본 논문의 고전적인 조합입니다.
$latex = 'uplatex -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
$max_repeat = 5;본질적으로 uplatex를 $latex에, dvipdfmx를 $dvipdf에 할당하고 $pdf_mode = 3를 설정하여 "DVI를 빌드한 다음 dvipdfmx를 사용하여 PDF로 변환" 경로를 선택합니다($pdf_mode = 1는 직접적으로 pdfLaTeX이고, 4는 LuaLaTeX). 색인은 upmendex를 거쳐서, 참고문헌은 upbibtex를 거쳐서 일본어를 잘 다룬다. %S, %O 및 %D는 소스, 옵션 및 출력 파일에 대한 latexmk의 자리 표시자입니다. 이제 VS Code 측에서는 단순히 latexmk (latexmkrc) 레시피를 선택하고 settings.json에서 엔진 선택을 인코딩하지 않습니다.
.latexmkrc 없이 settings.json에 모든 것을 보관하려면 자신만의 도구와 레시피를 정의하고 일본 레시피를 먼저 넣으세요. 다음은 LuaLaTeX로 일본어를 조판하는 자체 포함된 예입니다(luatexja/ltjsclasses를 통해 일본어를 설정하며 .latexmkrc나 dvipdfmx가 필요하지 않음).
{
"latex-workshop.latex.tools": [
{
"name": "lualatexmk",
"command": "latexmk",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"-lualatex",
"-outdir=%OUTDIR%",
"%DOC%"
],
"env": {}
}
],
"latex-workshop.latex.recipes": [
{
"name": "lualatexmk",
"tools": ["lualatexmk"]
}
],
"latex-workshop.latex.outDir": "%DIR%/out",
"latex-workshop.latex.autoBuild.run": "onSave"
}파일 상단에 % !TEX program = ... 또는 % !TEX root = ...와 같은 마법의 주석을 넣을 수도 있으며, LaTeX Workshop는 이를 존중합니다(latex-workshop.latex.build.enableMagicComments를 통해 비활성화). 레시피 시스템은 오늘날 권장되는 경로입니다. % !TEX root는 포함된 하위 파일을 편집하는 동안 기본 문서를 컴파일하려는 경우 다중 파일 프로젝트에서 유지됩니다.
루트 파일 고정
다중 파일 프로젝트에서 LaTeX Workshop가 잘못 추측하면 편집 중인 하위 파일을 직접 컴파일하려고 시도할 수 있습니다. 확장 프로그램은 \documentclass, \begin{document} 및 \input/\include 관계를 찾아 루트를 추론하지만, 챕터 파일이 많은 논문 크기 프로젝트의 경우 명시적인 방향이 더 안정적입니다.
% !TEX root = ../main.tex
\section{実験方法}
この章だけを編集中でも、ビルドは main.tex から始めます。- 항목 파일이 명시적으로 표시되도록
% !TEX root = ...를 하위 파일의 맨 위에 배치합니다. - 격리된 챕터 폴더가 아닌
main.tex가 포함된 프로젝트 루트에서 작업공간을 엽니다. - 수동 레시피 선택은 마법의 설명을 무시할 수 있으므로 팀 전체에서 일상적인 레시피 이름을 일관되게 유지하세요.
- 루트 선택에서 계속 메시지가 표시되면 프로젝트의
.vscode/settings.json에 정책을 고정하세요.
SyncTeX 통합
SyncTeX는 PDF의 소스 행과 위치 사이의 대응 관계를 기록합니다(위의 -synctex=1는 해당 매핑을 .synctex.gz에 기록합니다). 이를 통해 글쓰기 지점과 PDF 보기를 양방향으로 동기화할 수 있습니다. 내장된 PDF 뷰어(viewer를 tab로 설정)를 사용하는 것이 가장 매끄럽고 구성이 없는 경로입니다.
정방향 검색(소스 → PDF)은 편집 위치에서 PDF의 일치하는 지점으로 이동합니다. 단축키는 Ctrl+Alt+J(Mac에서는 Cmd+Option+J)입니다. 명령 팔레트에서 "LaTeX Workshop: SyncTeX from cursor"입니다. 빌드 직후 정방향 검색을 자동으로 실행하려면 latex-workshop.synctex.afterBuild.enabled를 true로 설정하세요.
역검색(PDF → 소스)은 PDF의 한 위치에서 일치하는 소스 행으로 다시 반대 방향으로 진행됩니다. 내장 탭 뷰어에서 PDF의 Ctrl-클릭(Mac에서는 Cmd-클릭)을 누르면 커서가 해당 라인으로 이동됩니다. 클릭 스타일은 latex-workshop.view.pdf.internal.synctex.keybinding, 즉 ctrl-click(기본값) 또는 double-click에 의해 설정됩니다. 정방향/역방향 쌍을 함께 배우면 긴 문서에서도 즉시 올바른 위치로 이동할 수 있습니다.
일본어로 된 SyncTeX의 경우 두 가지만 있으면 충분합니다. .latexmkrc에서 -synctex=1를 $latex에 전달하고(위의 예에서는 이미 수행됨) DVI($pdf_mode = 3)를 통해서도 upLaTeX + dvipdfmx가 SyncTeX 데이터를 전달한다는 것을 알아두십시오. 외부 뷰어가 있는 SyncTeX(latex-workshop.view.pdf.external.synctex.*)에는 추가 구성이 필요하므로 내장 탭에서 시작하는 것이 좋습니다.