WSL 高效開發環境建置：從安裝到生產力完全指南

# 以系統管理員權限開啟 PowerShell

# 啟用 WSL 功能
# 這個命令會啟用 Windows Subsystem for Linux 功能
# 需要重新啟動電腦才能生效
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 啟用虛擬機器平台
# WSL 2 需要虛擬機器平台支援
# 這是 WSL 2 運作的基礎
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重新啟動電腦
# 必須重新啟動才能使上述功能生效
Restart-Computer

# 重新開機後，設定 WSL 2 為預設版本
# 這樣之後安裝的 Linux 發行版都會使用 WSL 2
wsl --set-default-version 2

# 列出可用的 Linux 發行版
# 顯示 Microsoft Store 中所有可安裝的 Linux 發行版
wsl --list --online

# 安裝 Ubuntu 22.04 LTS
# 這是目前最穩定且廣泛使用的發行版之一
# 安裝過程會要求設定使用者名稱與密碼
wsl --install -d Ubuntu-22.04

# 驗證安裝
# 列出所有已安裝的 WSL 發行版
# -v 參數會顯示詳細資訊，包括版本號
wsl --list --verbose

# 更新 WSL 核心
# 確保使用最新的 WSL 核心版本
# 這能獲得最新的功能與安全性修復
wsl --update

# 檢查 WSL 版本
# 顯示 WSL 的版本資訊與已安裝的發行版
wsl --status

#!/bin/bash
# WSL Ubuntu 初始化配置腳本
# 
# 這個腳本會執行以下操作：
# 1. 更新系統套件
# 2. 安裝常用開發工具
# 3. 配置 Git
# 4. 安裝 Node.js 與 Python
# 5. 配置 shell 環境

# 更新套件索引
# 確保套件管理器有最新的套件清單
echo "更新套件索引..."
sudo apt update

# 升級所有已安裝的套件
# 將系統中所有套件更新到最新版本
echo "升級系統套件..."
sudo apt upgrade -y

# 安裝基礎開發工具
# build-essential 包含 gcc、g++、make 等編譯工具
# curl 與 wget 用於下載檔案
# git 用於版本控制
# vim 是文字編輯器
echo "安裝基礎開發工具..."
sudo apt install -y \
    build-essential \
    curl \
    wget \
    git \
    vim \
    tree \
    htop \
    net-tools

# 配置 Git
# 設定全域的使用者名稱與電子郵件
# 這些資訊會出現在 Git 提交記錄中
echo "配置 Git..."
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# 設定 Git 的預設編輯器為 vim
git config --global core.editor vim

# 設定 Git 的換行符處理
# input 表示在提交時將 CRLF 轉換為 LF
# 這對於跨平台開發很重要
git config --global core.autocrlf input

# 安裝 Node.js 使用 nvm
# nvm 是 Node.js 版本管理器，可以輕鬆切換不同版本
echo "安裝 Node.js 版本管理器 (nvm)..."
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 載入 nvm
# 執行 nvm 的初始化腳本
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安裝最新的 LTS 版本 Node.js
# LTS (Long Term Support) 版本更穩定
echo "安裝 Node.js LTS..."
nvm install --lts
nvm use --lts

# 驗證 Node.js 與 npm 安裝
node --version
npm --version

# 安裝 Python 開發環境
# Python 3 與 pip 套件管理器
echo "安裝 Python 開發環境..."
sudo apt install -y \
    python3 \
    python3-pip \
    python3-venv

# 升級 pip 到最新版本
python3 -m pip install --upgrade pip

# 配置 shell 環境
# 在 .bashrc 中加入自訂配置
echo "配置 shell 環境..."

# 加入自訂的 alias
cat >> ~/.bashrc << 'EOF'

# 自訂 alias
alias ll='ls -alF'
alias la='ls -A'
alias l='ls -CF'
alias gs='git status'
alias ga='git add'
alias gc='git commit'
alias gp='git push'

# 設定彩色提示符
export PS1='\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '

# Node.js 路徑
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
EOF

# 重新載入 .bashrc
source ~/.bashrc

echo "WSL 初始化完成！"
echo "請執行 'source ~/.bashrc' 來載入新的環境設定"

# .wslconfig 檔案
# 位置：C:\Users\<YourUsername>\.wslconfig
# 
# 這個檔案用於配置 WSL 2 虛擬機器的全域設定
# 修改後需要執行 wsl --shutdown 重新啟動 WSL 才能生效

[wsl2]
# 記憶體限制
# 設定 WSL 2 可以使用的最大記憶體
# 預設是系統記憶體的 50% 或 8GB（取較小值）
# 範例：限制為 8GB
memory=8GB

# 處理器核心數
# 設定 WSL 2 可以使用的處理器核心數
# 預設使用所有可用的核心
# 範例：限制為 4 個核心
processors=4

# 交換空間大小
# 設定 WSL 2 的虛擬記憶體大小
# 預設是實體記憶體的 25%
# 設定為 0 可以停用交換空間
# 範例：設定為 2GB
swap=2GB

# 交換檔案路徑
# 指定交換檔案的儲存位置
# 預設在 %USERPROFILE%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx

# 本地主機轉發
# 啟用後可以從 Windows 存取 WSL 中監聽的埠
# 預設為 true
localhostforwarding=true

# 巢狀虛擬化
# 允許在 WSL 2 中執行虛擬機器
# 某些容器化工作負載可能需要這個功能
# 預設為 false
nestedVirtualization=true

# 核心命令列參數
# 傳遞給 Linux 核心的額外參數
# 可以用於啟用特定的核心功能
# kernelCommandLine = vsyscall=emulate

# 安全啟動
# 是否啟用安全啟動
# 預設為 true
# safeMode=true

# 除錯控制台
# 啟用核心除錯控制台輸出
# 用於診斷核心問題
# debugConsole=false

# 在 Windows 上下載並安裝 Docker Desktop
# 從官方網站下載：https://www.docker.com/products/docker-desktop

# 安裝後，在 Docker Desktop 設定中：
# 1. 進入 Settings -> General
# 2. 勾選 "Use the WSL 2 based engine"
# 3. 進入 Settings -> Resources -> WSL Integration
# 4. 啟用想要使用 Docker 的 WSL 發行版

# 驗證 Docker 是否正確安裝（在 WSL 中執行）
docker --version
docker-compose --version

# 測試 Docker 執行
# 執行一個簡單的 hello-world 容器
docker run hello-world

# docker-compose.yml
# 定義一個完整的 Web 應用程式開發環境
# 包含 PostgreSQL 資料庫、Redis 快取與 Node.js 應用程式

version: '3.8'

# 定義服務
services:
  # PostgreSQL 資料庫服務
  postgres:
    # 使用官方的 PostgreSQL 14 映像檔
    image: postgres:14-alpine
    
    # 容器名稱
    container_name: dev_postgres
    
    # 環境變數配置
    environment:
      # 資料庫超級使用者密碼
      POSTGRES_PASSWORD: devpassword
      
      # 預設資料庫名稱
      POSTGRES_DB: appdb
      
      # 預設使用者名稱（預設為 postgres）
      POSTGRES_USER: devuser
    
    # 埠號映射
    # 將容器的 5432 埠映射到主機的 5432 埠
    ports:
      - "5432:5432"
    
    # 資料卷掛載
    # 持久化資料庫資料
    volumes:
      # 將資料庫資料儲存在 Docker 管理的卷中
      - postgres_data:/var/lib/postgresql/data
      
      # 掛載初始化 SQL 腳本
      # 容器啟動時會自動執行這個目錄中的 .sql 檔案
      - ./init-scripts:/docker-entrypoint-initdb.d
    
    # 健康檢查
    # 確保資料庫服務正常運作
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U devuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
    
    # 網路配置
    networks:
      - dev_network
  
  # Redis 快取服務
  redis:
    # 使用官方的 Redis Alpine 映像檔
    image: redis:7-alpine
    
    container_name: dev_redis
    
    # 埠號映射
    ports:
      - "6379:6379"
    
    # 啟動命令
    # 啟用 AOF 持久化
    command: redis-server --appendonly yes
    
    # 資料卷掛載
    volumes:
      - redis_data:/data
    
    # 健康檢查
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    
    networks:
      - dev_network
  
  # Node.js 應用程式服務
  app:
    # 使用 Node.js 18 Alpine 映像檔
    image: node:18-alpine
    
    container_name: dev_app
    
    # 工作目錄
    working_dir: /app
    
    # 環境變數
    environment:
      # Node.js 環境
      NODE_ENV: development
      
      # 資料庫連線字串
      DATABASE_URL: postgresql://devuser:devpassword@postgres:5432/appdb
      
      # Redis 連線字串
      REDIS_URL: redis://redis:6379
    
    # 埠號映射
    ports:
      - "3000:3000"
    
    # 資料卷掛載
    volumes:
      # 掛載當前目錄到容器的 /app
      # 這樣可以即時反映程式碼變更
      - .:/app
      
      # 使用匿名卷避免 node_modules 被覆蓋
      # WSL 與 Windows 之間的 node_modules 可能不相容
      - /app/node_modules
    
    # 啟動命令
    # 使用 nodemon 監視檔案變更並自動重啟
    command: sh -c "npm install && npm run dev"
    
    # 依賴關係
    # 等待資料庫與快取服務啟動
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    
    networks:
      - dev_network

# 定義資料卷
# 用於持久化資料
volumes:
  # PostgreSQL 資料卷
  postgres_data:
    driver: local
  
  # Redis 資料卷
  redis_data:
    driver: local

# 定義網路
# 所有服務在同一個網路中可以互相通訊
networks:
  dev_network:
    driver: bridge

# 在 WSL 中管理 Docker 的常用命令

# 啟動所有服務
# -d 參數表示在背景執行
docker-compose up -d

# 查看服務狀態
# 顯示所有容器的狀態、埠號映射等資訊
docker-compose ps

# 查看服務日誌
# -f 參數表示持續追蹤日誌輸出
docker-compose logs -f

# 查看特定服務的日誌
docker-compose logs -f app

# 進入容器的 shell
# 用於除錯或執行命令
docker-compose exec app sh

# 停止所有服務
# 容器會被停止但不會被刪除
docker-compose stop

# 停止並刪除所有容器
# -v 參數會同時刪除匿名卷
docker-compose down -v

# 重新建構映像檔
# 當 Dockerfile 或依賴項變更時使用
docker-compose build

# 重新建構並啟動服務
docker-compose up -d --build

# 清理未使用的資源
# 刪除停止的容器、未使用的網路與映像檔
docker system prune -a

# 查看 Docker 磁碟使用情況
docker system df

# 在 WSL 中安裝 VS Code 伺服器元件
# 實際上不需要手動安裝，Remote-WSL 會自動處理

# 從 WSL 中開啟 VS Code
# 這個命令會在 Windows 中啟動 VS Code
# 並自動連接到 WSL 環境
code .

# 如果這是第一次執行，VS Code 會自動安裝 WSL 伺服器元件
# 之後的啟動會更快

// .vscode/settings.json
// VS Code 工作區設定檔
{
  // 整合終端機設定
  "terminal.integrated.defaultProfile.linux": "bash",
  
  // 檔案監視排除
  // 排除不需要監視的目錄以提升效能
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/dist/**": true
  },
  
  // 檔案搜尋排除
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.git": true
  },
  
  // ESLint 配置
  "eslint.enable": true,
  "eslint.validate": [
    "javascript",
    "typescript"
  ],
  
  // Prettier 配置
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  
  // TypeScript 配置
  "typescript.updateImportsOnFileMove.enabled": "always",
  
  // Git 配置
  "git.autofetch": true,
  "git.confirmSync": false,
  
  // 編輯器配置
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.rulers": [80, 120],
  
  // 遠端開發設定
  // 指定在 WSL 中安裝的擴充套件
  "remote.extensionKind": {
    "ms-vscode.cpptools": ["workspace"]
  }
}

// .vscode/launch.json
// VS Code 除錯配置檔
{
  "version": "0.2.0",
  "configurations": [
    {
      // Node.js 應用程式除錯配置
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      
      // 要執行的程式進入點
      "program": "${workspaceFolder}/src/index.js",
      
      // 執行前先編譯 TypeScript（如果使用 TS）
      "preLaunchTask": "tsc: build - tsconfig.json",
      
      // 輸出配置
      "outFiles": [
        "${workspaceFolder}/dist/**/*.js"
      ],
      
      // 環境變數
      "env": {
        "NODE_ENV": "development"
      },
      
      // 控制台配置
      "console": "integratedTerminal",
      
      // 自動附加子程序
      "autoAttachChildProcesses": true
    },
    {
      // Docker 容器中的應用程式除錯配置
      "type": "node",
      "request": "attach",
      "name": "Attach to Docker",
      
      // 連接埠號（容器需要開放除錯埠）
      "port": 9229,
      
      // 本地檔案與遠端檔案的路徑映射
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app",
      
      // 重啟時自動重新附加
      "restart": true,
      
      // 跳過不需要除錯的檔案
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}