---

name: setup-wsl-dev-environment locale: wenyan-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-05-03" description: > Set up a WSL2 development environment on Windows including shell configuration, essential tools, Git, SSH keys, Node.js, Python, and cross-platform path management. Use when setting up a new Windows machine for development, configuring WSL2 for the first time, adding development tools to an existing WSL installation, or setting up cross-platform workflows that combine WSL and Windows tools. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: general complexity: intermediate language: multi tags: wsl, windows, linux, development, setup

設 WSL 境

備 WSL2 全境，跨臺以工。

用

• 新機初設→用
• WSL2 始配→用
• 既裝增工→用
• 跨臺流（WSL+Windows）→用

入

• 必：Win10/11 支 WSL2
• 可：所好 Linux（默 Ubuntu）
• 可：語（Node.js、Python、R）
• 可：餘工（Docker、tmux、fzf）

行

一：裝 WSL2

PowerShell（管）：

wsl --install
wsl --set-default-version 2

如囑→重啟。Ubuntu 默裝。

得：重啟後 wsl --list --verbose 示版二行。wsl 開 Linux 殼。

敗：裝敗→optionalfeatures.exe 手啟「虛擬機平臺」「Windows Subsystem for Linux」。舊版→需 Microsoft 核更。

二：設 WSL 限

於 Windows 家建 ~/.wslconfig：

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

得：.wslconfig 存於 Windows 家（如 C:\Users\Name\.wslconfig）。wsl --shutdown 重啟後限施。

敗：無效→驗位（Windows 家，非 WSL 家）。wsl --shutdown 重啟。

三：更與裝要

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential \
  curl \
  wget \
  git \
  git-lfs \
  vim \
  htop \
  tree \
  jq \
  ripgrep \
  fd-find \
  unzip \
  zip

建別號：

echo 'alias fd="fdfind"' >> ~/.bashrc

得：諸包無誤而裝。git --version、jq --version、rg --version、tree 皆行。

敗：裝敗→先 sudo apt update。包不在→驗 Ubuntu 版支否，或他源（snap、cargo、手裝）。

四：設 Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input
git config --global color.ui auto
git config --global core.editor vim

得：git config --list 示名、郵、默枝（main）、autocrlf（input）、編。

敗：未施→驗用 --global（非 --local）。察 ~/.gitconfig 含期項。

五：設 SSH 鑰

ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
# Add to GitHub: Settings > SSH and GPG keys

驗：ssh -T git@github.com

得：ssh -T git@github.com 返「Hi username! You've successfully authenticated.」鑰於 ~/.ssh/id_ed25519 與 .pub。

敗：認敗→驗公鑰加於 GitHub（Settings > SSH and GPG keys）。察 ssh-agent 行、ssh-add -l 示鑰。代→加 eval "$(ssh-agent -s)" 於 ~/.bashrc。

六：裝 Node.js（用 nvm）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

得：node --version 與 npm --version 返今 LTS。nvm ls 示裝版為默。

敗：nvm 不在→source ~/.bashrc 或開新端。腳本敗→閱後手執。

七：裝 Python（用 pyenv）

# Install build dependencies
sudo apt install -y make libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils \
  tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash

# Add to ~/.bashrc
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

pyenv install 3.12
pyenv global 3.12

得：python --version 返 3.12.x。pyenv versions 示裝版為全域。

敗：pyenv install 構誤→驗依皆裝。缺 libssl-dev 或 zlib1g-dev 為最常因。

八：設殼

加於 ~/.bashrc：

# History
export HISTSIZE=10000
export HISTFILESIZE=20000
export HISTCONTROL=ignoredups:erasedups
shopt -s histappend

# Navigation aliases
alias ll='ls -alF'
alias la='ls -A'
alias ..='cd ..'
alias ...='cd ../..'

# Development paths
export DEV_HOME="/mnt/d/dev/p"
alias dev='cd $DEV_HOME'

# Functions
mkcd() { mkdir -p "$1" && cd "$1"; }

# PATH additions
export PATH="$HOME/bin:$HOME/.local/bin:$PATH"

得：source ~/.bashrc 後，諸別號（ll、la、..、dev）皆行，mkcd 建並入。

敗：別號不在→驗加於 ~/.bashrc（非 ~/.bash_profile）。source 重載。

九：設 Claude Code CLI

# Add Claude CLI to PATH (after installation)
echo 'export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
which claude

得：which claude 返路（如 ~/.claude/local/node_modules/.bin/claude）。claude --version 印版。

敗：claude 不在→驗 PATH 加而 source。察 ~/.claude/local/ 真有。否→先依文裝。

十：跨臺路參

Windows	WSL
C:\Users\Name	/mnt/c/Users/Name
D:\dev\projects	/mnt/d/dev/projects
%APPDATA%	/mnt/c/Users/Name/AppData/Roaming

由 WSL 開 Windows Explorer：explorer.exe .

得：路換明、可由 WSL 訪 Windows 路（如 ls /mnt/c/Users/）；explorer.exe . 開當下目。

敗：/mnt/c/ 不可訪→驗 WSL automount 設。察 /etc/wsl.conf [automount]。wsl --shutdown 重啟。

驗

• WSL2 行於正分發
• Git 設正身
• SSH 鑰加 GitHub 而連驗
• Node.js 裝而行
• Python 裝而行
• 殼別號與函皆行
• Claude Code CLI 可訪

忌

• /mnt/ 訪緩：常用案存於 WSL（~/）為佳。/mnt/ 留共用 Windows 工
• 行尾：core.autocrlf=input 防 CRLF。編設 LF
• 權誤：/mnt/ 檔權或誤。加於 /etc/wsl.conf：[automount]\noptions = "metadata,umask=22,fmask=11"
• Windows Defender：除 WSL 目於即時掃以增效

參

• configure-git-repository - Git 庫詳設
• configure-mcp-server - MCP 需 WSL 境
• write-claude-md - 為案設 AI 助