Entwicklung in WSL

Die WSL-Erweiterung für Visual Studio Code ermöglicht es Ihnen, das Windows Subsystem für Linux (WSL) als Ihre vollständige Entwicklungsumgebung direkt aus VS Code zu nutzen. Sie können in einer Linux-basierten Umgebung entwickeln, Linux-spezifische Toolchains und Dienstprogramme verwenden und Ihre Linux-basierten Anwendungen bequem von Windows aus ausführen und debuggen.

Die Erweiterung führt Befehle und andere Erweiterungen direkt in WSL aus, sodass Sie Dateien im WSL oder im gemounteten Windows-Dateisystem (z. B. /mnt/c) bearbeiten können, ohne sich Gedanken über Pfadprobleme, binäre Kompatibilität oder andere Cross-OS-Herausforderungen machen zu müssen. Die Erweiterung installiert den VS Code Server innerhalb von WSL. Der Server ist unabhängig von einer bestehenden VS Code-Installation in WSL.

Dadurch kann VS Code eine Entwicklungserfahrung auf lokaler Ebene bieten – einschließlich vollständiger IntelliSense (Vervollständigungen), Code-Navigation und Debugging – unabhängig davon, wo Ihr Code gehostet wird.

Erste Schritte

Hinweis: Nach dem Lesen dieses Themas können Sie mit dem Einführungs-WSL-Tutorial beginnen.

Installation

Um loszulegen, müssen Sie

1. Das Windows Subsystem für Linux zusammen mit Ihrer bevorzugten Linux-Distribution installieren.

   Hinweis: WSL 1 hat einige bekannte Einschränkungen für bestimmte Entwicklungsarten. Außerdem funktionieren Erweiterungen, die in Alpine Linux installiert sind, aufgrund von glibc-Abhängigkeiten im nativen Quellcode innerhalb der Erweiterung möglicherweise nicht. Einzelheiten finden Sie im Artikel Remote-Entwicklung und Linux.

2. Visual Studio Code auf der Windows-Seite installieren (nicht in WSL).

   Hinweis: Wenn Sie während der Installation zur Auswahl zusätzlicher Aufgaben aufgefordert werden, stellen Sie sicher, dass Sie die Option Zu PATH hinzufügen aktivieren, damit Sie einen Ordner in WSL einfach mit dem Befehl code öffnen können.

3. Die WSL-Erweiterung installieren. Wenn Sie mit anderen Remote-Erweiterungen in VS Code arbeiten möchten, können Sie das Remote Development-Erweiterungspaket installieren.

Einen Remote-Ordner oder Arbeitsbereich öffnen

Vom WSL-Terminal aus

Das Öffnen eines Ordners innerhalb des Windows Subsystem für Linux in VS Code ist sehr ähnlich wie das Öffnen eines Windows-Ordners über die Eingabeaufforderung oder PowerShell.

1. Öffnen Sie ein WSL-Terminalfenster (über das Startmenü oder durch Eingabe von wsl in der Eingabeaufforderung/PowerShell).

2. Navigieren Sie zu einem Ordner, den Sie in VS Code öffnen möchten (einschließlich, aber nicht beschränkt auf Windows-Dateisystem-Mounts wie /mnt/c).

3. Geben Sie im Terminal code . ein. Wenn Sie dies zum ersten Mal tun, sollten Sie sehen, wie VS Code Komponenten herunterlädt, die für die Ausführung in WSL benötigt werden. Dies sollte nur kurze Zeit dauern und ist nur einmal erforderlich.

   Hinweis: Wenn dieser Befehl nicht funktioniert, müssen Sie möglicherweise Ihr Terminal neu starten, oder Sie haben VS Code bei der Installation nicht zu Ihrem Pfad hinzugefügt.

4. Nach einem Moment erscheint ein neues VS Code-Fenster, und Sie sehen eine Benachrichtigung, dass VS Code den Ordner in WSL öffnet.

   

   VS Code konfiguriert sich nun weiter in WSL und hält Sie über den Fortschritt auf dem Laufenden.

5. Nach Abschluss sehen Sie nun eine WSL-Anzeige unten links und können VS Code wie gewohnt verwenden!

   

Das war's! Alle VS Code-Vorgänge, die Sie in diesem Fenster ausführen, werden in der WSL-Umgebung ausgeführt, von der Bearbeitung und Dateivorgängen bis hin zu Debugging, der Verwendung von Terminals und vielem mehr.

Von VS Code aus

Alternativ können Sie ein WSL-Fenster direkt aus VS Code öffnen

1. Starten Sie VS Code.
2. Drücken Sie F1, wählen Sie WSL: Mit WSL verbinden für die Standard-Distro oder WSL: Mit WSL über Distro verbinden für eine bestimmte Distro.
3. Verwenden Sie das Menü Datei, um Ihren Ordner zu öffnen.

Wenn Sie bereits einen Ordner geöffnet haben, können Sie auch den Befehl WSL: Ordner in WSL erneut öffnen verwenden. Sie werden gefragt, welche Distro verwendet werden soll.

Wenn Sie sich in einem WSL-Fenster befinden und die aktuelle Eingabe in einem lokalen Fenster öffnen möchten, verwenden Sie WSL: In Windows erneut öffnen.

Aus der Windows-Eingabeaufforderung

Um ein WSL-Fenster direkt von einer Windows-Eingabeaufforderung aus zu öffnen, verwenden Sie den Befehlszeilenparameter --remote

code --remote wsl+<Distroname> <Pfad in WSL>

zum Beispiel: code --remote wsl+Ubuntu /home/jim/projects/c

Wir müssen erraten, ob der Eingabepfad eine Datei oder ein Ordner ist. Wenn er eine Dateiendung hat, wird er als Datei betrachtet.

Um zu erzwingen, dass ein Ordner geöffnet wird, fügen Sie einen Schrägstrich zum Pfad hinzu oder verwenden Sie

code --folder-uri vscode-remote://wsl+Ubuntu/home/ubuntu/folder.with.dot

Um zu erzwingen, dass eine Datei geöffnet wird, fügen Sie --goto hinzu oder verwenden Sie

code --file-uri vscode-remote://wsl+Ubuntu/home/ubuntu/fileWithoutExtension

Arbeiten mit Git

Wenn Sie denselben Repository in WSL und Windows bearbeiten, stellen Sie sicher, dass Sie konsistente Zeilenenden konfigurieren. Weitere Informationen finden Sie unter Tipps und Tricks.

Sie können auch Passwörter vermeiden, indem Sie WSL so konfigurieren, dass der Windows Git Credential Manager verwendet wird. Weitere Informationen finden Sie unter Tipps und Tricks.

Verwalten von Erweiterungen

VS Code führt Erweiterungen an zwei Orten aus: lokal auf der UI/Client-Seite oder in WSL. Während Erweiterungen, die die VS Code-UI beeinflussen, wie Themes und Snippets, lokal installiert werden, befinden sich die meisten Erweiterungen innerhalb von WSL.

Wenn Sie eine Erweiterung über die Erweiterungsansicht installieren, wird sie automatisch am richtigen Ort installiert. Nach der Installation können Sie anhand der Kategorienzuordnung erkennen, wo eine Erweiterung installiert ist. Es gibt eine Kategorie Lokal – Installiert und eine für WSL.

Hinweis: Wenn Sie Erweiterungsautor sind und Ihre Erweiterung nicht ordnungsgemäß funktioniert oder am falschen Ort installiert wird, lesen Sie Erweiterungen für Remote-Entwicklung unterstützen für Details.

Lokale Erweiterungen, die tatsächlich remote ausgeführt werden müssen, werden in der Kategorie Lokal – Installiert ausgegraut und deaktiviert angezeigt. Wählen Sie Installieren, um eine Erweiterung auf Ihrem Remote-Host zu installieren.

Sie können auch alle lokal installierten Erweiterungen in WSL installieren, indem Sie zur Erweiterungsansicht gehen und über die Wolke-Schaltfläche rechts neben der Titelleiste von Lokal – Installiert Lokale Erweiterungen in WSL installieren: {Name} auswählen. Dies zeigt ein Dropdown an, in dem Sie auswählen können, welche lokal installierten Erweiterungen in Ihrer WSL-Instanz installiert werden sollen.

Terminal in WSL öffnen

Das Öffnen eines Terminals in WSL aus VS Code ist einfach. Sobald ein Ordner in WSL geöffnet ist, wird jedes Terminalfenster, das Sie in VS Code öffnen (Terminal > Neues Terminal), automatisch in WSL anstelle von lokal ausgeführt.

Sie können auch den Befehl code aus diesem Terminalfenster verwenden, um eine Reihe von Vorgängen auszuführen, wie z. B. das Öffnen einer neuen Datei oder eines neuen Ordners in WSL. Geben Sie code --help ein, um die verfügbaren Optionen über die Befehlszeile anzuzeigen.

Debuggen in WSL

Sobald Sie einen Ordner in WSL geöffnet haben, können Sie den VS Code-Debugger auf dieselbe Weise verwenden, wie wenn Sie die Anwendung lokal ausführen. Wenn Sie beispielsweise eine Startkonfiguration in launch.json auswählen und das Debugging starten (F5), wird die Anwendung auf dem Remote-Host gestartet und der Debugger daran angehängt.

Details zur Konfiguration der Debugging-Funktionen von VS Code in .vscode/launch.json finden Sie in der Debugging-Dokumentation.

WSL-spezifische Einstellungen

Die lokalen Benutzereinstellungen von VS Code werden auch wiederverwendet, wenn Sie einen Ordner in WSL geöffnet haben. Dies hält Ihre Benutzererfahrung konsistent, aber Sie möchten möglicherweise einige dieser Einstellungen zwischen Ihrem lokalen Computer und WSL variieren. Glücklicherweise können Sie, sobald Sie eine Verbindung zu WSL hergestellt haben, auch WSL-spezifische Einstellungen vornehmen, indem Sie den Befehl Einstellungen: Remote-Einstellungen öffnen aus der Befehlspalette (F1) ausführen oder den Tab Remote im Einstellungen-Editor auswählen. Diese überschreiben alle lokalen Einstellungen, die Sie haben, immer wenn Sie einen Ordner in WSL öffnen.

Fortgeschritten: Skript zur Umgebungs­einrichtung

Wenn VS Code Remote in WSL gestartet wird, werden keine Shell-Startskripte ausgeführt. Dies geschah, um Probleme mit Startskripten zu vermeiden, die für Shells optimiert sind. Wenn Sie zusätzliche Befehle ausführen oder die Umgebung ändern möchten, kann dies in einem Skript zur Einrichtung ~/.vscode-server/server-env-setup (Insiders: ~/.vscode-server-insiders/server-env-setup) erfolgen. Wenn das Skript vorhanden ist, wird es verarbeitet, bevor der Server gestartet wird.

Das Skript muss ein gültiges Bourne-Shell-Skript sein. Beachten Sie, dass ein ungültiges Skript verhindert, dass der Server startet. Wenn Sie ein Skript haben, das den Start des Servers verhindert, müssen Sie eine reguläre WSL-Shell verwenden und das Setup-Skript löschen oder umbenennen.

Überprüfen Sie das WSL-Protokoll (WSL: Protokoll anzeigen) auf Ausgaben und Fehler.

Fortgeschritten: WSL 2-Ordner in einem Container öffnen

Wenn Sie WSL 2 und das WSL 2-Backend von Docker Desktop verwenden, können Sie die Dev Containers-Erweiterung verwenden, um mit Quellcode zu arbeiten, der in WSL gespeichert ist! Befolgen Sie einfach diese Schritte

1. Wenn nicht bereits geschehen, installieren und richten Sie die WSL 2-Unterstützung von Docker Desktop ein.

   Tipp: Gehen Sie zu Einstellungen > Ressourcen > WSL-Integration und aktivieren Sie die Docker-Integration mit der WSL-Distribution, die Sie verwenden werden.

2. Wenn nicht bereits geschehen, installieren Sie die Dev Containers-Erweiterung zusammen mit der WSL-Erweiterung.

3. Öffnen Sie als Nächstes Ihren Quellcode-Ordner in WSL, wie Sie es normalerweise tun würden.

4. Sobald Ihr Ordner in WSL geöffnet ist, wählen Sie Dev Containers: In Container erneut öffnen aus der Befehlspalette (F1).

5. Wenn der Ordner keine .devcontainer/devcontainer.json-Datei enthält, werden Sie aufgefordert, einen Startpunkt aus einer filterbaren Liste oder einer vorhandenen Dockerfile oder Docker Compose-Datei (falls vorhanden) auszuwählen.

   

6. Das VS Code-Fenster (Instanz) wird neu geladen und beginnt mit dem Erstellen des Dev-Containers. Eine Fortschrittsbenachrichtigung gibt Status-Updates.

   

7. Nach Abschluss des Builds wird VS Code automatisch eine Verbindung zum Container herstellen. Sie können nun mit Ihrem Quellcode aus dem Container heraus arbeiten.

Weitere Informationen finden Sie in der Dev Containers-Dokumentation.

Bekannte Einschränkungen

Dieser Abschnitt enthält eine Liste gängiger bekannter Probleme mit WSL. Die Absicht ist nicht, eine vollständige Liste von Problemen bereitzustellen, sondern einige der häufigsten Probleme hervorzuheben, die bei WSL auftreten.

Eine Liste der aktiven Probleme im Zusammenhang mit WSL finden Sie hier.

Ich erhalte eine Fehlermeldung EACCES: permission denied beim Umbenennen eines Ordners im geöffneten Arbeitsbereich in WSL 1

Dies ist ein bekanntes Problem mit der WSL-Dateisystemimplementierung (Microsoft/WSL#3395, Microsoft/WSL#1956), das durch den von VSCode aktiven Dateibeobachter verursacht wird. Das Problem wird erst in WSL 2 behoben sein.

Um das Problem zu vermeiden, setzen Sie remote.WSL.fileWatcher.polling auf true. Die polling-basierte Dateibeobachtung hat jedoch Leistungseinbußen bei großen Arbeitsbereichen.

Für große Arbeitsbereiche möchten Sie das Polling-Intervall erhöhen: remote.WSL.fileWatcher.pollingInterval und die beobachteten Ordner steuern: files.watcherExclude.

WSL 2 hat dieses Problem mit dem Dateibeobachter nicht und ist auch nicht von der neuen Einstellung betroffen.

Golang in WSL 1

Node.js in WSL 1

Git-Beschränkungen

Wenn Sie ein Git-Repository über SSH klonen und Ihr SSH-Schlüssel eine Passphrase hat, können die Pull- und Synchronisierungsfunktionen von VS Code beim Remote-Betrieb hängen bleiben. Verwenden Sie entweder einen SSH-Schlüssel ohne Passphrase, klonen Sie über HTTPS oder führen Sie git push von der Befehlszeile aus, um das Problem zu umgehen.

Einschränkungen der Container Tools-Erweiterung

Obwohl die Container Tools-Erweiterung sowohl remote als auch lokal ausgeführt werden kann, können Sie sie, wenn sie bereits lokal installiert ist, nicht auf einem Remote-SSH-Host installieren, ohne sie zuerst lokal zu deinstallieren. Wir werden dieses Problem in einer zukünftigen VS Code-Version beheben.

Einschränkungen bei Erweiterungen

Viele Erweiterungen funktionieren ohne Änderungen in WSL. In einigen Fällen können jedoch bestimmte Funktionen Änderungen erfordern. Wenn Sie auf ein Problem mit einer Erweiterung stoßen, lesen Sie hier für eine Zusammenfassung gängiger Probleme und Lösungen, die Sie dem Erweiterungsautor bei der Meldung des Problems nennen können.

Darüber hinaus funktionieren einige Erweiterungen, die in einer WSL-Instanz unter Verwendung einer Alpine Linux-basierten Distribution installiert sind, aufgrund von glibc-Abhängigkeiten in nativem Code innerhalb der Erweiterung möglicherweise nicht. Einzelheiten finden Sie im Artikel Remote-Entwicklung mit Linux.

Häufig gestellte Fragen

Warum werde ich aufgefordert, die Standard-Distro zu ändern?

Wenn Sie WSL: Mit WSL über Distro verbinden verwenden und auf WSL vor dem Windows 10 Mai 2019 Update (Version 1903) ausgeführt wird, werden Sie aufgefordert, die Standard-Distribution zu wechseln, da der WSL-Befehl nur auf der Standard-Distro funktionieren kann, da er die Option -d noch nicht unterstützt.

Sie können die Standard-Distribution jederzeit manuell wechseln, indem Sie wslconfig.exe verwenden.

Zum Beispiel

wslconfig /setdefault Ubuntu

Sie können sehen, welche Distributionen Sie installiert haben, indem Sie

wslconfig /l

Ich erhalte eine Fehlermeldung über eine fehlende Bibliothek oder Abhängigkeit

Einige Erweiterungen sind auf Bibliotheken angewiesen, die in der Standardinstallation bestimmter WSL Linux-Distributionen nicht gefunden werden. Sie können Ihrer Linux-Distribution zusätzliche Bibliotheken hinzufügen, indem Sie den Paketmanager verwenden. Führen Sie für Ubuntu und Debian-basierte Distributionen sudo apt-get install <paket> aus, um die benötigten Bibliotheken zu installieren. Lesen Sie die Dokumentation Ihrer Erweiterung oder der erwähnten Laufzeitumgebung für zusätzliche Installationsdetails.

Welche Konnektivitätsanforderungen hat die WSL-Erweiterung?

Die WSL-Erweiterung und der VS Code Server benötigen ausgehende HTTPS-Konnektivität (Port 443) zu

• update.code.visualstudio.com
• vscode.download.prss.microsoft.com
• marketplace.visualstudio.com
• *.gallerycdn.vsassets.io (Azure CDN)

Einige Erweiterungen (wie C#) laden sekundäre Abhängigkeiten von download.microsoft.com oder download.visualstudio.microsoft.com herunter. Andere (wie Visual Studio Live Share) haben möglicherweise zusätzliche Konnektivitätsanforderungen. Konsultieren Sie die Dokumentation der Erweiterung für Details, wenn Sie Probleme haben.

Die gesamte andere Kommunikation zwischen dem Server und dem VS Code-Client erfolgt über einen zufälligen lokalen TCP-Port. Eine Liste der Speicherorte, auf die VS Code selbst Zugriff benötigt, finden Sie im Artikel Netzwerkverbindungen.

Ich befinde mich hinter einem Proxy und habe Konnektivitätsprobleme

Proxy-Einstellungen fehlen möglicherweise auf der Windows- oder der WSL-Seite.

Wenn ein Remote-Fenster außerhalb von VS Code geöffnet wird, versucht die WSL-Erweiterung, den VS Code-Server auf der Windows-Seite herunterzuladen. Daher verwendet sie die Proxy-Konfiguration der Windows-Seite

• geerbt von den OS-Einstellungen
• wie in Netzwerkverbindungen in Visual Studio Code beschrieben

Wenn der Remote-VS Code von einem WSL-Terminal gestartet wird, erfolgt der Download mit wget in der WSL-Distribution. Proxy-Einstellungen können konfiguriert werden in

• wget-Proxy-Einstellungen: https://stackoverflow.com/questions/11211705/how-to-set-proxy-for-wget
• manuell im Server-Setup-Skript

Sobald der Server gestartet ist und läuft, werden die Proxy-Einstellungen auf der Registerkarte Remote verwendet.

Kann ich eine Erweiterung erzwingen, lokal/remote ausgeführt zu werden?

Erweiterungen werden normalerweise so entwickelt und getestet, dass sie entweder lokal oder remote ausgeführt werden, nicht beides. Wenn eine Erweiterung dies jedoch unterstützt, können Sie sie in Ihrer settings.json-Datei erzwingen, an einem bestimmten Speicherort auszuführen.

Zum Beispiel erzwingt die folgende Einstellung die lokale Ausführung der Erweiterung Container Tools und die remote Ausführung der Erweiterung Remote - SSH: Konfigurationsdateien bearbeiten anstelle ihrer Standardwerte

"remote.extensionKind": {
    "ms-azuretools.vscode-containers": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

Ein Wert von "ui" anstelle von "workspace" zwingt die Erweiterung, auf der lokalen UI/Client-Seite ausgeführt zu werden. Dies sollte in der Regel nur zum Testen verwendet werden, es sei denn, in der Dokumentation der Erweiterung ist etwas anderes angegeben, da dies Erweiterungen beschädigen kann. Weitere Einzelheiten finden Sie im Artikel Erweiterungen für Remote-Entwicklung unterstützen.

Was muss ich als Erweiterungsautor tun?

Die VS Code-Erweiterungs-API abstrahiert lokale/remote Details, sodass die meisten Erweiterungen ohne Änderungen funktionieren. Da Erweiterungen jedoch beliebige Node-Module oder Laufzeiten verwenden können, gibt es Situationen, in denen Anpassungen vorgenommen werden müssen. Wir empfehlen Ihnen, Ihre Erweiterung zu testen, um sicherzustellen, dass keine Aktualisierungen erforderlich sind. Details finden Sie unter Unterstützung der Remote-Entwicklung.

Fragen oder Feedback

• Siehe Tipps und Tricks oder die FAQ.
• Auf Stack Overflow suchen.
• Fügen Sie eine Funktionsanfrage hinzu oder melden Sie ein Problem.
• Zu unserer Dokumentation oder VS Code selbst beitragen.
• Details finden Sie in unserem CONTRIBUTING-Leitfaden.