VS Code (LaTeX Workshop)

Fügen Sie die Erweiterung LaTeX Workshop zu Visual Studio Code hinzu, und aus einem Allzweck-Codeeditor wird eine ernstzunehmende LaTeX-Umgebung: Er wird bei jedem Speichern kompiliert, zeigt PDF in einer Registerkarte nebeneinander an und ermöglicht das Wechseln zwischen Quelle und PDF in beide Richtungen. Auf dieser Seite werden die Einrichtung, die Funktionsweise von Builds (Rezepte und Tools) und die SyncTeX-Integration erläutert.

Was LaTeX Workshop ist

VS Code setzt TeX nicht selbst. Die eigentliche Kompilierung erfolgt durch eine Distribution, die Sie auf Ihrem Computer installieren – TeX Live (oder MiKTeX / MacTeX). LaTeX Workshop von James Yu ist die Brücke zwischen dem Editor und dieser Distribution: Es startet Builds, zeigt eine Vorschau von PDF an und fügt Vervollständigung, Syntaxhervorhebung, Sprung zur Definition für \ref/\cite, eine Gliederungsansicht und mehr hinzu. Sein Marktplatz ID ist James-Yu.latex-workshop mit über 5 Millionen Installationen – praktisch die Standarderweiterung LaTeX im VS Code-Ökosystem.

Die einzige Voraussetzung ist, dass die TeX-Befehle auf Ihrem PATH erreichbar sind. Die Erweiterung erzeugt einfach ausführbare Dateien wie latexmk oder pdflatex als untergeordnete Prozesse. Wenn also latexmk --version in einem Terminal funktioniert, funktioniert die Erweiterung mit ziemlicher Sicherheit auch. Umgekehrt ist die Auswahl einer Engine oder die Konfiguration japanischer Schriftarten eine Angelegenheit der Distribution, nicht der Erweiterung.

Zuerst einmal im Terminal kompilieren

Erstellen Sie vor dem Optimieren der VS Code-Einstellungen dasselbe Projekt einmal in einem Terminal. Wenn latexmk dort nicht laufen kann, kann LaTeX Workshop es auch nicht starten. Probieren Sie für ein erstes Dokument eines davon aus dem Projektordner aus:

latexmk -pdf main.tex
# 日本語 upLaTeX を .latexmkrc に書いた場合 / if .latexmkrc selects upLaTeX
latexmk main.tex

Sobald die Fehler PATH und fehlende Pakete dort behoben sind, wird jeder Fehler auf der VS Code-Seite auf Rezepte, Root-Dateierkennung oder den PDF-Viewer eingegrenzt. Wenn der Terminal-Build funktioniert, die Erweiterung jedoch fehlschlägt, überprüfen Sie settings.json: Ausgabeverzeichnis, Rezeptname und Platzhalter sind die üblichen Verdächtigen.

Einrichtung

Die Schritte sind einfach. Installieren Sie VS Code, installieren Sie eine Distribution wie TeX Live (im Jahr 2026 TeX Live 2026) und stellen Sie sicher, dass sie auf Ihrem PATH vorhanden ist. Öffnen Sie dann die Erweiterungsansicht (Ctrl/Cmd+Shift+X), suchen Sie nach „LaTeX Workshop“ und installieren Sie es. Direkt nach dem Ändern von PATH starten Sie VS Code neu – idealerweise das gesamte OS – damit die neue Umgebung übernommen wird. Öffnen Sie eine .tex-Datei und über das TeX-Aktivitätsleistensymbol auf der linken Seite erhalten Sie Build- und Vorschaubefehle.

Settings live in settings.json (von Ctrl/Cmd+, Settings UI aus verwenden Sie „Zxqph5xz (JSON) öffnen“ oben rechts; Sie können entweder die globale Benutzerdatei oder eine pro Projekt .vscode/settings.json bearbeiten). Die drei Schlüssel, die es zunächst zu wissen gilt, sind:

• latex-workshop.latex.outDir – wohin Zwischendateien und PDF gehen. Standardmäßig %DIR% (neben .tex). Stellen Sie es auf z.B. out sorgt dafür, dass Ihr Quellordner übersichtlich bleibt.
• latex-workshop.latex.autoBuild.run – was einen automatischen Build auslöst: onFileChange (Standard; überwacht Abhängigkeiten), onSave (beim Speichern) oder never (nur manuell). Wenn Sie vorhersehbares Verhalten wünschen, ist onSave eine sichere Wahl.
• latex-workshop.view.pdf.viewer – wo PDF erscheint: tab (Standard; eine Registerkarte innerhalb von VS Code), browser oder external. Für reibungsloses SyncTeX ist tab die beste Wahl.

Ein minimaler Ausgangspunkt ist genau dieser: Sammeln Sie die Ausgabe in out/, bauen Sie beim Speichern auf und zeigen Sie PDF in der integrierten Registerkarte an:

{
  "latex-workshop.latex.outDir": "%DIR%/out",
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.view.pdf.viewer": "tab"
}

%DIR% ist ein Platzhalter, der auf das Verzeichnis der Root-Datei erweitert wird, die verarbeitet wird; es taucht in den folgenden Rezepten wieder auf. Nach einem Build kann die Erweiterung über latex-workshop.latex.autoClean.run auch Zwischendateien (.aux, .log, …) aufräumen oder behalten, aber die Festlegung des Ausgabeverzeichnisses und des Triggers reicht aus, um ein Gefühl dafür zu bekommen.

Erstellen Sie Rezepte und Werkzeuge

Builds in LaTeX Workshop haben zwei Ebenen: „Tools“ und „Rezepte“. Ein Tool (latex-workshop.latex.tools) definiert einen einzelnen auszuführenden Befehl – name, command (die ausführbare Datei) und args. Ein Rezept (latex-workshop.latex.recipes) ist eine geordnete Folge von Werkzeugen, mit einem name- und einem tools-Array, in dem die Werkzeugnamen aufgelistet sind. Ein Ablauf wie „pdflatex → bibtex → pdflatex → pdflatex“, bei dem der Bibliographiedurchlauf ausgeführt und dann erneut ausgeführt wird, wird als ein Rezept ausgedrückt.

Ohne Konfiguration verwendet die Erweiterung ihre integrierten Standardrezepte. Das erste ist ein einzelnes latexmk, und das ist die beabsichtigte Standardeinstellung (wenn latex-workshop.latex.recipe.default "first" ist, wird das oberste Rezept in der Liste ausgewählt; setzen Sie es auf "lastUsed", um sich das Rezept zu merken, das Sie zuletzt ausgewählt haben). Da latexmk Abhängigkeiten prüft und genau so oft wie nötig erneut ausführt, müssen Sie nie Durchgänge für Querverweise, das Inhaltsverzeichnis oder die Bibliographie zählen. Das Standardtool latexmk ist ungefähr wie folgt definiert:

{
  "name": "latexmk",
  "command": "latexmk",
  "args": [
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-outdir=%OUTDIR%",
    "%DOC%"
  ],
  "env": {}
}

Lesen der Argumente: -synctex=1 gibt die unten besprochenen SyncTeX-Daten aus; -interaction=nonstopmode läuft direkt durch, anstatt für die Eingabe bei einem Fehler anzuhalten; -file-line-error gibt Fehler als „Datei:Zeile:Nachricht“ aus, sodass Sie leicht zur fehlerhaften Stelle springen können. -pdf weist latexmk an, PDF direkt über pdfLaTeX zu erzeugen. %OUTDIR% wird zu Ihrem outDir erweitert und %DOC% zum Pfad der Stammdatei ohne Erweiterung (andere Platzhalter sind %DOCFILE% = Dateiname ohne Erweiterung und %DIR% = das Stammverzeichnis).

Die Standardrezepte umfassen auch die Engine-Varianten latexmk (lualatex) und latexmk (xelatex) sowie latexmk (latexmkrc), das latexmk %DOC% ohne zusätzliche Argumente ausführt und alles auf ein .latexmkrc verschiebt. Für Japaner ist der Ansatz „Alles in .latexmkrc stecken“ der sauberste. Legen Sie ein .latexmkrc im Projektstammverzeichnis ab und benennen Sie die Engine und den Konverter. Hier ist ein upLaTeX + dvipdfmx-Aufbau – die klassische Kombination für japanische Arbeiten in den Naturwissenschaften:

$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;

Im Wesentlichen weisen Sie uplatex $latex, dvipdfmx $dvipdf zu und stellen $pdf_mode = 3 so ein, dass der Pfad „Zxqph20xz erstellen, dann mit dvipdfmx in PDF konvertieren“ ausgewählt wird ($pdf_mode = 1 ist direkt pdfLaTeX, 4 ist). LuaLaTeX). Der Index läuft über upmendex und die Bibliographie über upbibtex, das Japanisch gut beherrscht. %S, %O und %D sind die Platzhalter von latexmk für die Quelle, Optionen und Ausgabedatei. Jetzt wählen Sie auf der VS Code-Seite einfach das latexmk (latexmkrc)-Rezept aus und kodieren niemals die Engine-Auswahl in settings.json.

Wenn Sie lieber alles in settings.json ohne .latexmkrc behalten möchten, definieren Sie Ihr eigenes Werkzeug und Rezept und stellen Sie das japanische Rezept an die erste Stelle. Hier ist ein eigenständiges Beispiel für den japanischen Schriftsatz mit LuaLaTeX (der Japanisch über luatexja/ltjsclasses setzt und weder .latexmkrc noch dvipdfmx benötigt):

{
  "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"
}

Sie können auch magische Kommentare wie % !TEX program = ... oder % !TEX root = ... an den Anfang einer Datei setzen, und LaTeX Workshop berücksichtigt sie (über latex-workshop.latex.build.enableMagicComments deaktivieren). Das Rezeptsystem ist heute der empfohlene Weg; % !TEX root verdient seinen Unterhalt bei Projekten mit mehreren Dateien, wenn Sie das Hauptdokument kompilieren und gleichzeitig eine enthaltene Unterdatei bearbeiten möchten.

Anheften der Root-Datei

Wenn LaTeX Workshop in einem Projekt mit mehreren Dateien falsch liegt, versucht es möglicherweise, die untergeordnete Datei, die Sie gerade bearbeiten, direkt zu kompilieren. Die Erweiterung leitet den Stamm ab, indem sie nach den Beziehungen \documentclass, \begin{document} und \input/\include sucht. Bei Projekten in der Größe einer Abschlussarbeit mit vielen Kapiteldateien ist die explizite Richtung jedoch stabiler.

% !TEX root = ../main.tex

\section{実験方法}
この章だけを編集中でも、ビルドは main.tex から始めます。

• Platzieren Sie % !TEX root = ... an der Spitze der untergeordneten Dateien, damit die Eintragsdatei explizit ist.
• Öffnen Sie den Arbeitsbereich im Projektstammverzeichnis, das main.tex enthält, und nicht in einem isolierten Kapitelordner.
• Die manuelle Rezeptauswahl kann magische Kommentare außer Kraft setzen. Sorgen Sie daher dafür, dass der alltägliche Rezeptname im gesamten Team konsistent ist.
• Wenn Sie weiterhin zur Root-Auswahl aufgefordert werden, pinnen Sie die Richtlinie im .vscode/settings.json des Projekts an.

SyncTeX-Integration

SyncTeX zeichnet die Entsprechung zwischen Quellzeilen und Positionen im PDF auf (der obige -synctex=1 schreibt diese Zuordnung in einen .synctex.gz). Damit können Sie Ihren Schreibplatz und die PDF-Ansicht in beide Richtungen synchron halten. Die Verwendung des integrierten PDF-Viewers (viewer auf tab eingestellt) ist der reibungsloseste Weg ohne Konfiguration.

Vorwärtssuche (Quelle → PDF) springt von Ihrer Bearbeitungsposition zur passenden Stelle im PDF. Die Verknüpfung lautet Ctrl+Alt+J (auf dem Mac Cmd+Option+J); In der Befehlspalette lautet es „LaTeX Workshop: SyncTeX from cursor“. Um die Vorwärtssuche direkt nach einem Build automatisch auszuführen, setzen Sie latex-workshop.synctex.afterBuild.enabled auf true.

Inverse Suche (PDF → Quelle) geht in die andere Richtung, von einer Stelle in PDF zurück zur passenden Quellzeile. Im integrierten Tab-Viewer bewegt ein Ctrl-Klick (Cmd-Klick auf Mac) im PDF den Cursor zu dieser Zeile. Der Klickstil wird durch latex-workshop.view.pdf.internal.synctex.keybinding festgelegt, entweder ctrl-click (Standard) oder double-click. Lernen Sie das Vorwärts-/Rückwärtspaar gemeinsam und Sie können selbst in einem langen Dokument sofort an die richtige Stelle springen.

Für SyncTeX auf Japanisch genügen zwei Dinge: Übergeben Sie -synctex=1 an $latex in Ihrem .latexmkrc (im obigen Beispiel bereits geschehen) und beachten Sie, dass upLaTeX + dvipdfmx die SyncTeX-Daten auch über DVI ($pdf_mode = 3) weiterleitet. SyncTeX mit einem externen Viewer (latex-workshop.view.pdf.external.synctex.*) erfordert mehr Konfiguration, daher ist die integrierte Registerkarte der empfohlene Ausgangspunkt.