Docker on kenji.blog

使用 Docker 构建可重现的本地开发环境的步骤

Sun, 13 Sep 2026 01:00:00 +0900

1. 引言：摆脱“在我的机器上能运行”的困境

在软件开发现场，由于开发者之间的环境差异而导致的“在我的机器上能运行（It works on my machine）”问题，长期以来一直是许多项目浪费时间的因素。操作系统的差异、安装的语言版本、库的依赖关系、全局安装的工具冲突等，本地环境始终面临着“状态的不确定性”。

从根本上解决这些挑战的是以 Docker 为首的容器技术，以及 基础设施即代码 (IaC) 的范式。通过将本地开发环境容器化，实现了操作系统级别的隔离，并可以将环境本身与代码库一起进行版本控制。

本文将深入讲解如何充分利用 Docker、Docker Compose 和 VSCode DevContainers，构建一个**“无论谁在何时、哪台机器上启动，状态都分毫不差的可重现的本地开发环境”**的步骤，并从数学角度深入探讨其背后的深层技术机制。

2. 基础设施即代码 (IaC) 与容器技术的契合度

IaC 的原则及其在本地环境中的应用

基础设施即代码 (IaC) 是一种通过机器可读的定义文件，而非手动流程来管理和配置基础架构的方法。IaC 的核心原则包含以下要素：

声明式方法 (Declarative Approach)：定义“最终应该是什么状态”，而不是“如何改变状态”。
幂等性 (Idempotency)：无论执行多少次脚本，始终保证相同的结果（状态）。
版本控制 (Version Control)：基础设施的状态作为代码保存在 Git 等 VCS 中，从而可以追踪更改历史并进行同行评审。

在本地开发环境中实践 IaC，意味着使用 Dockerfile、docker-compose.yml 和 devcontainer.json 将开发环境的“理想状态”代码化。这样，新加入团队的成员也可以通过克隆存储库并运行一条命令，立即开始开发，实现丝滑的入职体验。

支撑容器技术的内核功能

容器技术与虚拟机（VM）等基于管理程序的虚拟化不同，它是一种轻量级的虚拟化技术，在共享宿主机操作系统内核的同时，隔离进程（Isolation）。为了实现这一点，主要使用了 Linux 内核的以下功能：

Namespaces（命名空间）：为每个进程提供独立的系统资源视图（PID、网络、挂载点、用户等）。
Cgroups (Control Groups, 控制组)：限制和分配进程可以使用的物理资源（CPU、内存、磁盘 I/O 等）。
UnionFS (联合文件系统)：一种透明地叠加多个目录树（层）并将它们显示为一个文件系统的技术。Docker 的镜像层依赖于这项技术。

让我们考虑一下资源限制的数学模型。假设宿主机的总内存容量为 $M_{\text{total}}$，在宿主机上运行的 $n$ 个容器的内存限制为 $m_i$。考虑到操作系统和其他进程消耗的基础内存 $M_{\text{os}}$，系统稳定运行的必要条件可以用以下不等式表示：

$$ \sum_{i=1}^{n} m_i \le M_{\text{total}} - M_{\text{os}} $$

通过使用 Cgroups 严格定义每个容器的 $m_i$，即使特定容器发生内存泄漏，也能防止 OOM (Out Of Memory) Killer 导致其他容器或整个宿主系统崩溃。

3. 高效的 Dockerfile 设计：掌握多阶段构建

实现可重现环境的第一步是设计定义应用程序运行环境的 Dockerfile。在这里，我们将以 Python (FastAPI) 为例，讲解利用多阶段构建的，安全且轻量级的 Dockerfile 最佳实践。

多阶段构建是一种在一个 Dockerfile 中使用多个 FROM 指令的方法，将构建环境（包含编译器和开发工具的繁重环境）与执行环境（仅包含所需工件的轻量级环境）分离。

实用的 Python FastAPI Dockerfile

以下代码是结合 Poetry 依赖项管理和多阶段构建的高级 Dockerfile 示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


# ---------------------------------------------------------
# Stage 1: Builder (构建环境)
# ---------------------------------------------------------
FROM python:3.11-slim AS builder

# 设置所需的环境变量
ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 POETRY_VERSION=1.6.1 \
 POETRY_HOME="/opt/poetry" \
 POETRY_VIRTUALENVS_IN_PROJECT=true \
 POETRY_NO_INTERACTION=1

# 安装依赖包
RUN apt-get update && apt-get install -y --no-install-recommends \
 curl build-essential && \
 curl -sSL https://install.python-poetry.org | python3 - && \
 apt-get clean && rm -rf /var/lib/apt/lists/*

ENV PATH="$POETRY_HOME/bin:$PATH"

WORKDIR /app

# 复制并安装依赖关系文件
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ---------------------------------------------------------
# Stage 2: Runtime (运行环境)
# ---------------------------------------------------------
FROM python:3.11-slim AS runtime

ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 PATH="/app/.venv/bin:$PATH"

# 创建一个最小的非特权用户
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# 仅从 builder 复制虚拟环境（依赖项）
COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv

# 复制应用程序代码
COPY --chown=appuser:appuser ./src /app/src

# 切换到非特权用户
USER appuser

# 容器启动时的默认命令
ENTRYPOINT ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

多阶段构建对镜像大小的数学评估

假设单阶段构建时的镜像大小为 $S_{\text{single}}$，应用多阶段构建后的镜像大小为 $S_{\text{multi}}$。大小缩减率 $R$ 的计算公式如下：

$$ R = \left( 1 - \frac{S_{\text{multi}}}{S_{\text{single}}} \right) \times 100 \ (\%) $$

例如，假设 $S_{\text{single}}$ 包含操作系统的基础镜像（约 110MB）、开发包（如 gcc 约 150MB）、Poetry 本身（约 40MB）、项目的依赖库（约 80MB）和源代码（约 5MB），总计 385MB。另一方面，在 $S_{\text{multi}}$ 中，仅将依赖库（80MB）和源代码（5MB）复制到基础镜像（110MB）中，因此总计为 195MB。

$$ R = \left( 1 - \frac{195}{385} \right) \times 100 \approx 49.35\% $$

通过引入多阶段构建，镜像大小可减少约一半。镜像大小的减小直接关系到从注册表提取（Pull）时间的缩短、磁盘空间的节省，以及通过减少攻击面（Attack Surface）来提高安全性。

4. 使用 Docker Compose 编排多个容器

在现代 Web 应用程序开发中，由 Web 服务器、数据库和缓存服务器等多个组件协同工作的微服务架构非常普遍。为了在本地环境中集中管理这些组件，我们使用 docker-compose.yml。

这次，我们将在本地构建一个“Web (FastAPI)”、“数据库 (PostgreSQL)”和“缓存 (Redis)”的三层架构系统。

架构图 (Mermaid)

下图是表示本地机器中各容器、网络和卷之间关系的块图。

graph TD
User["宿主机 (浏览器/curl)"] -->|Localhost:8000| Web["FastAPI Web 容器"]
subgraph "Docker 桥接网络 (app-network)"
Web -->|Port 5432| DB["PostgreSQL 容器"]
Web -->|Port 6379| Redis["Redis 容器"]
end
DB --> Volume1["命名卷 (postgres_data)"]
Redis --> Volume2["命名卷 (redis_data)"]
HostDir["宿主机源代码 (./src)"] -.->|Bind Mount| Web

docker-compose.yml 的实现与详细讲解

以下是足以承受实际环境构建的强大 docker-compose.yml 示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


version: '3.8'

services:
 web:
 build:
 context: .
 target: runtime
 container_name: dev_web
 ports:
 - "8000:8000"
 volumes:
 - ./src:/app/src:ro  # 以只读方式挂载宿主机代码（用于热重载）
 environment:
 - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
 - REDIS_URL=redis://redis:6379/0
 env_file:
 - .env
 depends_on:
 db:
 condition: service_healthy
 redis:
 condition: service_started
 networks:
 - app-network
 command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

 db:
 image: postgres:15-alpine
 container_name: dev_db
 ports:
 - "5432:5432"
 environment:
 POSTGRES_USER: postgres
 POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
 POSTGRES_DB: ${POSTGRES_DB}
 volumes:
 - postgres_data:/var/lib/postgresql/data
 networks:
 - app-network
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U postgres -d ${POSTGRES_DB}"]
 interval: 5s
 timeout: 5s
 retries: 5

 redis:
 image: redis:7-alpine
 container_name: dev_redis
 ports:
 - "6379:6379"
 volumes:
 - redis_data:/data
 networks:
 - app-network
 command: ["redis-server", "--appendonly", "yes"]

volumes:
 postgres_data:
 redis_data:

networks:
 app-network:
 driver: bridge

卷 (Volumes) 与数据持久化

容器原则上是“无状态的（Stateless）”且“短暂的（Ephemeral）”。一旦销毁容器，其内部的数据也会随之消失。为了保留数据库的数据或缓存，需要将宿主机的文件系统区域挂载到容器中。

Bind Mount (绑定挂载)：对应上述 web 服务中的 ./src:/app/src:ro。将宿主机的特定目录直接映射到容器内。用于将本地的代码编辑立即反映到容器中（热重载）。从安全角度出发，最佳实践是添加 :ro (Read-Only) 选项，以防止容器端修改宿主机的源代码。
Named Volume (命名卷)：对应 postgres_data 和 redis_data。是由 Docker 内部（如 /var/lib/docker/volumes/）管理的区域，比绑定挂载具有更好的 I/O 性能，并且能吸收不同操作系统间文件系统的差异。数据库的持久化务必使用此方式。

网络 (Networking) 与服务发现

Docker Compose 默认会为每个项目创建一个专有的桥接网络，即上述的 app-network。属于同一网络的容器之间，可以使用“服务名（如 db, redis）”作为主机名进行名称解析（DNS 解析），而不是使用 IP 地址。例如，可以从 Web 容器通过 postgresql://postgres:password@db:5432/mydb 这样的 URL 访问数据库。由此，无论是在本地环境还是生产环境，都能通过环境变量透明地切换连接目标。

运行状况检查与启动顺序控制

depends_on 指令用于控制容器的启动顺序，但仅指定 depends_on 会在“DB 容器启动”的阶段就启动 Web 容器。实际上，DB 的初始化过程（PostgreSQL 进程启动和表准备）需要几秒钟的时间，因此 Web 容器发起的 DB 连接可能会报错。为了防止这种情况发生，可以定义 healthcheck 并指定 condition: service_healthy，这样就能确认“DB 已处于可以接受连接请求的状态”后，再启动 Web 容器。

5. 环境变量管理与安全性 (.env)

绝对应该避免将数据库密码或 API 密钥等敏感信息硬编码到 docker-compose.yml 中，这是一种反模式。相反，我们应该使用环境变量文件 .env 注入这些值。

在项目根目录下创建一个 .env 文件。

1
2
3
4


# .env 文件 (请将其添加到 .gitignore 中以排除在 Git 管理之外)
POSTGRES_PASSWORD=supersecretpassword
POSTGRES_DB=devdb
API_SECRET_KEY=dev_secret_key_12345

Docker Compose 默认会读取执行目录下的 .env 文件，并展开 YAML 文件中的 ${VAR_NAME} 占位符。通过这种方法，无需修改基础架构代码，即可安全地管理本地、临时和生产等不同环境的配置值。

6. VSCode DevContainers 带来的极致开发体验

到目前为止，我们已经使用 Docker 构建了一个强大的后端环境。然而，我们还可以更进一步。通过使用 VSCode DevContainers (Remote - Containers) 功能，可以将编辑器（VSCode）本身的后端运行在容器内部。

这样一来，本地机器上甚至不需要安装 Python 或 Node.js，从 Linter（flake8/eslint）、格式化工具（black/prettier）到 IDE 扩展，所有的内容都可以在代码库中定义并由整个团队共享。

devcontainer.json 配置

在项目根目录下创建一个 .devcontainer 目录，并在其中放置配置文件。

.devcontainer/devcontainer.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
 "name": "Python FastAPI Dev Environment",
 "dockerComposeFile": ["../docker-compose.yml"],
 "service": "web",
 "workspaceFolder": "/app",
 "customizations": {
 "vscode": {
 "settings": {
 "python.defaultInterpreterPath": "/app/.venv/bin/python",
 "python.formatting.provider": "black",
 "editor.formatOnSave": true
 },
 "extensions": [
 "ms-python.python",
 "ms-python.vscode-pylance",
 "ms-python.black-formatter",
 "tamasfe.even-better-toml"
 ]
 }
 },
 "forwardPorts": [8000, 5432, 6379],
 "remoteUser": "appuser",
 "postCreateCommand": "poetry install"
}

将该文件包含在存储库中，当在 VSCode 中打开该项目时，系统会提示“在容器中重新打开（Reopen in Container）”，只需点击一下，就会启动所有必需的容器，安装扩展程序，并立即准备好进行编码。这真是一种如同魔法般的体验。

7. 请求处理序列与性能建模

我们通过序列图来确认在构建的本地开发环境中的 Web 应用程序请求处理的生命周期，并探讨其性能的数学模型。

序列图（请求流程）

sequenceDiagram
participant Client as "浏览器 / VSCode"
participant Web as "FastAPI (Web)"
participant Redis as "Redis 缓存"
participant DB as "PostgreSQL"
Client->>Web: "GET /api/users/123"
activate Web
Web->>Redis: "检查缓存 user:123"
activate Redis
alt "Cache Hit (缓存命中/有数据)"
Redis-->>Web: "返回缓存的用户数据"
Web-->>Client: "200 OK (快速响应)"
else "Cache Miss (缓存未命中/无数据)"
Redis-->>Web: "Null (未找到)"
deactivate Redis
Web->>DB: "SELECT * FROM users WHERE id = 123"
activate DB
DB-->>Web: "返回数据库行"
deactivate DB
Web->>Redis: "设置 user:123 数据 (TTL: 60s)"
activate Redis
Redis-->>Web: "OK"
deactivate Redis
Web-->>Client: "200 OK (标准响应)"
end
deactivate Web

处理延迟 (Latency) 的数学模型

在上述系统中，我们对平均请求处理时间 $T_{\text{total}}$ 进行数学建模。将各处理步骤的延迟定义如下：

$T_{\text{net}}$: 客户端与 Web 容器之间的网络延迟
$T_{\text{app}}$: 应用程序端纯粹的处理时间（如序列化等）
$T_{\text{cache}}$: 在 Redis 中读取和写入所花费的时间
$T_{\text{db}}$: 执行 PostgreSQL 查询所花费的时间
$p_{\text{miss}}$: 缓存未命中率（$0 \le p_{\text{miss}} \le 1$）

此时，平均响应时间可以通过以下期望值计算公式表示：

$$ T_{\text{total}} = T_{\text{net}} + T_{\text{app}} + T_{\text{cache}} + p_{\text{miss}} \times (T_{\text{db}} + T_{\text{cache\_write}}) $$

在本地开发环境（Docker 内部）中，$T_{\text{net}}$ 几乎接近于 0。但是，值得注意的是绑定挂载时的 I/O 性能。特别是在 Windows/macOS 上使用 Docker Desktop 时，由于宿主机操作系统和 VM（容器）之间的文件共享开销，$T_{\text{app}}$（代码加载时间等）容易变得过高。为了消除这个性能瓶颈，强烈建议利用前面提到的 DevContainers 将整个源代码放在命名卷内，或者采用在 WSL2（Windows Subsystem for Linux 2）原生环境中运行 Docker 引擎的架构。

8. Docker 构建的性能优化：层缓存策略

在编写 Dockerfile 时，是否理解“层缓存（Layer Cache）”机制将大幅改变构建时间。 Docker 会在遇到 Dockerfile 的每个指令（如 FROM, RUN, COPY 等）时创建文件系统差异（层），并将其作为缓存保留下来。在重新构建时，会重用未发生变更的层的缓存。

一个重要的原则是：“按更改频率从低到高的顺序编写”。

考虑对代码更改影响构建时间的建模。设总构建时间为 $T_{\text{build}}$，每一步的执行时间为 $T_{\text{layer}_i}$，是否命中缓存为布尔值 $c_i \in \{0, 1\}$（命中缓存时为 1）。

$$ T_{\text{build}} = T_{\text{init}} + \sum_{i=1}^{n} (1 - c_i) \times T_{\text{layer}_i} $$

一旦在第 $k$ 层发生缓存未命中（$c_k = 0$），则其后所有层 $j > k$ 的缓存都将失效（$c_j = 0$）。

1
2
3
4


# 反面教材 (先复制了源代码)
COPY ./src /app/src
COPY pyproject.toml poetry.lock ./
RUN poetry install

在上面的例子中，仅仅修改了一行代码，最初的 COPY 就会导致缓存未命中，进而使得极其耗时的 RUN poetry install 每次都会被执行。

1
2
3
4


# 好的示例 (先解析并安装依赖项)
COPY pyproject.toml poetry.lock ./
RUN poetry install
COPY ./src /app/src

这样编写的话，即使更改了源代码，poetry install 这一层的缓存 ($c_i = 1$) 依然有效，构建时间就能从几分钟大幅缩短到几秒钟。

9. 故障排除与技巧

以下列出在运行本地环境时常遇到的问题及解决方案。

端口冲突错误 如果出现类似 Bind for 0.0.0.0:8000 failed: port is already allocated 的错误，说明本地机器上有其他进程正在使用该端口。可以修改宿主机一侧的端口号，如 ports: - "8080:8000"，即可解决。
磁盘空间耗尽 长期使用 Docker 时，可能会累积未使用的镜像或卷（Dangling Images / Volumes），从而占用几十 GB 的磁盘空间。建议定期运行以下命令清理系统：
1

docker system prune -a --volumes
文件权限问题 在 Linux 环境下使用绑定挂载时，如果在容器内创建的文件，所有者可能会变成 root，导致在宿主机端无法编辑。可以通过在 Dockerfile 中创建一个非特权用户，并使其 UID/GID 与宿主机操作系统上自己的 UID/GID（例如：1000:1000）一致来解决该问题。

10. 结语：可重现性带来的开发速度提升

通过结合 Docker、Docker Compose 和 VSCode DevContainers，您可以打造出一个“无论谁启动环境，状态都能完全一致”的稳固的本地开发环境。

将 IaC 的范式引入本地环境，不仅仅是缩短了初始设置时间。它消除了在更改基础架构配置时的不安，简化了新技术栈的实验，并顺利过渡到 CI/CD 管道，这极大地提升了整个开发周期的速度和质量。

请务必运用本文讲解的最佳实践——如通过多阶段构建优化镜像大小、使用运行状况检查控制依赖关系、以及编写意识到层缓存的 Dockerfile，为您的项目带来极致的开发体验（DX: Developer Experience）。

WSL2（Windows Subsystem for Linux）终极开发环境配置指南

Sat, 12 Sep 2026 23:00:00 +0900

在Windows上提供Linux原生开发环境的“WSL2（Windows Subsystem for Linux 2）”，已经成为现代软件开发中不可或缺的工具。然而，是继续在默认状态下使用，还是在理解架构的基础上进行适当的调优，这在性能和开发体验上将会产生天壤之别。

在本文中，我们将从WSL2核心架构的解析开始，到最大化发挥性能的设置、舒适的终端环境的构建、与Docker和VS Code的无缝协同，以及高级网络配置，以超过1万字的篇幅，彻底为您讲解专业工程师所追求的“终极开发环境”的完整构建步骤。

1. WSL2的架构与从WSL1的演进

为了完全释放WSL2的潜力，首先理解其内部结构非常重要。初代WSL（WSL1）和WSL2在Windows上执行Linux二进制文件的方法有着根本的不同。

WSL1：系统调用转换层

WSL1采用了一种将Linux系统调用实时转换（Translation）为Windows NT API的机制。由于它不使用虚拟机（VM），因此具有资源开销非常小的优点。然而，完全模拟文件系统的I/O操作等复杂的系统调用是非常困难的，特别是在处理Node.js的 npm install 和Git的仓库操作等涉及大量小文件的任务时，会导致令人绝望的性能下降。

WSL2：轻量级实用程序VM和完整的Linux内核

WSL2的架构进行了革新，由微软构建的真正Linux内核直接运行在**利用Hyper-V架构子集的“轻量级实用程序VM”**之上。这保证了系统调用100%的兼容性，并且通过使用基于Linux原生的ext4文件系统的虚拟磁盘（VHDX），文件I/O的性能与WSL1相比得到了显著的提升。

下面的Mermaid图表展示了WSL1和WSL2在结构上的差异。

flowchart TD
subgraph "Windows OS Environment"
A["Windows NT内核"]
A --> F["NTFS文件系统 (C: 驱动器)"]
end
subgraph "WSL2 Architecture"
B["Hyper-V虚拟机管理程序"]
B --> C["轻量级实用程序VM"]
C --> D["Linux内核 (Microsoft)"]
D --> E["Ubuntu用户空间 (glibc, bash等)"]
D --> G["ext4虚拟磁盘 (.vhdx)"]
end
A -.->|"Plan 9 (9P) 协议网络文件共享"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

从这个架构中得出的重要教训是，“对Linux端文件（VHDX内）的访问速度极快，但由于通过9P协议，对Windows端文件（/mnt/c/）的访问则非常缓慢”。项目的源代码必须始终放置在WSL端的个人主目录（~）或其子目录下。

2. 性能的数学分析：为什么WSL2这么快？

让我们使用数学模型来定量评估WSL2的性能提升。在软件开发中，最耗时的操作之一就是涉及大量文件I/O的处理（例如：库的安装和编译）。

某个处理过程的整体执行时间 $T_{total}$，可以表示为CPU运算时间 $T_{compute}$ 与磁盘I/O耗时 $T_{io}$ 的总和。

$$ T_{total} = T_{compute} + T_{io} $$

在WSL1的情况下，由于需要将Linux端的操作转换为NTFS操作而产生开销，因此I/O时间可以建模如下。其中，$n$ 为文件操作的次数，$t_{ntfs\_syscall}$ 为Windows端的系统调用执行时间，$t_{trans}$ 为转换层的开销。

$$ T_{wsl1\_io} = \sum_{i=1}^{n} (t_{ntfs\_syscall_i} + t_{trans_i}) $$

另一方面，在WSL2的情况下，由于内核直接对ext4文件系统发出I/O，因此开销仅为虚拟化带来的极小延迟 $t_{virt}$。

$$ T_{wsl2\_io} = \sum_{i=1}^{n} (t_{ext4_i} + t_{virt_i}) $$

在常规的文件系统中，由于 $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$，当 $n$ 非常大（进行数万到数十万次文件操作）时，WSL1和WSL2的I/O时间差将呈指数级拉开。

此外，假设虚拟化环境中CPU运算的开销比率为 $\rho$，在最新的硬件辅助虚拟化（Intel VT-x / AMD-V）下，$\rho \approx 0.01 \sim 0.03$（约1%~3%）。因此，即使在纯粹的计算任务中，也能发挥出与原生Linux环境相差无几的 $97\% \sim 99\%$ 的性能。

3. 安装与基础构建

在Windows 10/11中，WSL2的安装变得非常简单。只需以管理员权限打开PowerShell，并执行以下命令即可。

1
2
3
4
5
6


# 默认会安装WSL2和Ubuntu
wsl --install

# 如果要指定特定的发行版
# 可以通过 wsl --list --online 查看支持的发行版
wsl --install -d Ubuntu-24.04

安装并重启后，首次启动时会要求您设置UNIX用户名和密码。该用户与Windows用户是独立的，仅在WSL内有效。

如果您已经在使用了WSL1，可以通过以下命令将其转换为WSL2。

1
2
3
4
5


# 将现有的发行版转换为WSL2
wsl --set-version Ubuntu 2

# 将以后添加的发行版默认设置为WSL2
wsl --set-default-version 2

4. 资源控制的秘诀：.wslconfig 和 wsl.conf

WSL2最大的陷阱之一就是“内存的无限制消耗（Vmmem进程的膨胀）”。由于WSL2利用了Linux内核的页面缓存，每次进行I/O操作时都会无休止地吞噬主机（Windows）的内存。为了防止这种情况，必须通过配置文件来限制资源。

WSL2的配置文件分为两个：影响整个Windows的 .wslconfig，以及影响各发行版内部的 wsl.conf。

4.1. .wslconfig (Windows端)

在Windows的用户配置文件夹（C:\Users\<用户名>\.wslconfig）中创建文件，以控制对VM的资源分配。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# C:\Users\<用户名>\.wslconfig
[wsl2]
# 分配给VM的最大内存量。建议为主机总内存的50%~75%左右
memory=16GB

# 使用的CPU核心数（省略时使用全部核心）
processors=8

# 交换文件（Swap）的大小
swap=8GB

# 交换文件的保存位置（如果想要节省C盘空间）
# swapfile=D:\\wsl\\swap.vhdx

# 启用localhost转发（以便从Windows端通过localhost访问WSL）
localhostForwarding=true

# 自动释放内存（仅限Windows 11）
# 动态释放页面缓存，防止Vmmem膨胀
autoMemoryReclaim=dropcache

[experimental]
# Windows 11 22H2及之后版本可用的高级网络功能
# 这使得IPv6支持以及在WSL和Windows之间共享同一个IP地址成为可能
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Linux端)

编辑WSL内的 /etc/wsl.conf，以控制发行版特有的行为。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# /etc/wsl.conf (在WSL内部编辑)
[network]
# 禁用WSL启动时自动生成的 /etc/resolv.conf
# 在想要设置自定义DNS（例: 8.8.8.8）时非常有用
generateResolvConf=false

# 设置自定义主机名
hostname=WSL-DevNode

[automount]
# 挂载Windows驱动器时的设置
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# 将C盘的挂载点从 /mnt/c 更改为 /c（缩短路径）
root=/

[boot]
# 启用systemd（WSL 0.67.6及之后版本）
# 这使得snap和各种守护进程（如Docker等）能够原生运行
systemd=true

[user]
# 默认登录的用户
default=kenji

要使这些设置生效，需要在PowerShell中执行 wsl --shutdown，完全停止WSL VM后再重新启动。

5. 终极终端环境：Zsh + Powerlevel10k

仅仅使用默认的bash是无法提高生产力的。将拥有强大补全功能和绝佳可视性的Zsh，与超快的“Powerlevel10k”主题结合，能够打造出最强的命令提示符。

5.1. Windows Terminal的安装与设置

从Microsoft Store中安装“Windows Terminal”。打开JSON设置（settings.json），将默认配置文件设置为WSL（Ubuntu），并将字体更改为面向开发的Nerd Font（例如：HackGen Console NF 或 MesloLGS NF）。

5.2. Zsh与Oh My Zsh的安装

在WSL终端中执行以下命令。

1
2
3
4
5
6


# 更新软件包并安装Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# 执行Oh My Zsh的安装脚本
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. Powerlevel10k与插件的安装

安装进一步增强Zsh功能的插件（语法高亮和输入补全）以及Powerlevel10k主题。

1
2
3
4
5
6
7
8


# Powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

# zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

编辑 ~/.zshrc，启用主题和插件。

1
2
3
4
5


# ~/.zshrc的修改点
ZSH_THEME="powerlevel10k/powerlevel10k"

# 添加到插件数组中
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

保存并执行 source ~/.zshrc 后，将启动Powerlevel10k的设置向导（p10k configure）。请按照屏幕上的指示，自定义您喜欢的提示符（提示符风格、是否有图标、显示的信息等）。Git的分支名及状态、Node.js的版本、命令的执行时间等都能实时显示，开发效率将得到飞跃性提升。

6. VS Code Remote - WSL的无缝集成

在WSL2开发中，能从Windows端安装的IDE（Visual Studio Code）无缝访问WSL内部文件的机制，就是“Remote - WSL”扩展功能。

架构解析

以下的时序图展示了VS Code是如何与WSL2进行通信的。

sequenceDiagram
autonumber
participant U as "开发者"
participant V as "VS Code界面 (Windows)"
participant S as "VS Code服务器 (WSL2)"
participant F as "ext4文件系统 (WSL2)"
U->>V: "在WSL终端中输入 `code .`"
V->>S: "通过Vsock建立RPC连接"
Note over V,S: 不使用TCP/IP，通过Hyper-V套接字通信
S->>F: "读取源文件 / 运行Linter"
F-->>S: "返回数据与分析结果"
S-->>V: "将Language Server结果推送到界面"
V-->>U: "显示语法高亮与错误信息"

Windows端的VS Code仅仅作为一个“瘦客户端（UI）”发挥作用，而Language Server、调试器、终端执行等繁重的处理全部由WSL端的“VS Code服务器”来完成。这样一来，无需在Windows端安装Node.js或Python，只需在WSL端即可保持环境的整洁。

必备的VS Code设置

从VS Code的“扩展”中安装 “WSL” (ms-vscode-remote.remote-wsl)。之后，在WSL终端中进入项目目录，只需执行 code .，就能在Windows端以打开该目录的状态启动VS Code。

重要注意事项（换行符问题）： Windows和Linux的换行符不同（Windows是 CRLF，Linux是 LF）。在WSL上进行开发时，请务必将Git的 core.autocrlf 设置以及VS Code中文件的默认设置统一为 LF。如果忽略这一点，您在执行Shell脚本或Docker容器时可能会被莫名其妙的错误所困扰。

1
2


# 在WSL端设置Git的换行符
git config --global core.autocrlf input

在VS Code的 settings.json（远程设置）中也添加以下内容。

1
2
3
4


{
 "files.eol": "\n",
 "terminal.integrated.defaultProfile.linux": "zsh"
}

7. Docker Desktop与WSL2 Integration的优化

在WSL2环境中使用Docker，主要有两种方式。

安装 Docker Desktop for Windows，并启用WSL2集成功能
在WSL2内部（如Ubuntu等）直接安装 原生的Docker Engine

方式1：Docker Desktop（推荐）

由于在GUI中进行管理以及在Windows/WSL之间进行容器的透明访问更为容易，在大多数情况下推荐使用这种方式。请在Docker Desktop的设置（Settings）中确认以下内容。

勾选 General -> Use the WSL 2 based engine。
勾选 Resources -> WSL Integration -> Enable integration with my default WSL distro，并打开要使用的发行版（如Ubuntu）的开关。

如此一来，您就可以直接在WSL2的终端执行 docker 命令，与Docker守护进程的通信将通过Docker Desktop管理的专用轻量级VM（docker-desktop 以及 docker-desktop-data）来进行。

方式2：直接安装原生的Docker Engine

由于企业网络的限制（例如规避Docker Desktop的商业收费）或想要将性能开销降到最低的情况，可以在 /etc/wsl.conf 中启用 systemd 后，像在纯粹的Ubuntu服务器上一样安装Docker。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 在启用了systemd的WSL2 Ubuntu上，Docker官方安装步骤的摘要
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加仓库
echo \
 "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
 "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 将当前用户添加到docker组（以便无需sudo即可运行）
sudo usermod -aG docker $USER

重启后，systemctl start docker 就能像在原生Linux环境中一样正常运行，并发挥出极高的性能。

8. SSH密钥的集成：在Windows和WSL中无缝认证

在进行Git的SSH克隆或通过SSH连接远程服务器时，如果在Windows端和WSL端分别管理不同的SSH密钥会非常麻烦。为了兼顾安全性与便利性，我们将进行设置，把运行在Windows端的SSH Agent（或1Password等密码管理器）桥接到WSL端。

在此，我们将讲解一种最安全且现代的方式：利用1Password的SSH Agent功能或Windows的OpenSSH Authentication Agent，并通过 npiperelay 和 socat 将其转发到WSL2的UNIX域套接字的方法。

ssh-agent的套接字转发

通常，作为Windows命名管道（Named Pipe）提供的SSH Agent，需要转换为WSL端的套接字文件。利用 wsl-ssh-agent 或1Password提供的功能可以很轻松地实现。

在1Password的设置界面中，启用“开发人员” -> “使用 SSH 代理”。然后，在WSL端的 ~/.zshrc 或 ~/.bashrc 中添加以下设置，以便在登录时自动绑定套接字。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 追加到 ~/.zshrc（使用1Password SSH Agent时的示例）
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# 如果WSL启动时套接字不存在，或进程未绑定，则使用socat和npiperelay进行转发
ALREADY_RUNNING=$(ps -aux | grep "[n]piperelay.exe -ei -s //./pipe/openssh-ssh-agent" | wc -l)
if [ $ALREADY_RUNNING -eq 0 ]; then
 if [ -S $SSH_AUTH_SOCK ]; then
 rm $SSH_AUTH_SOCK
 fi
 # 在后台启动socat，将Windows端的Named Pipe连接到WSL端的UNIX套接字
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

※需要事先在Windows端安装 npiperelay.exe 并配置好环境变量路径。

此设置完成后，从WSL终端执行 ssh-add -l 时，就会显示在1Password或Windows端注册的SSH公钥列表。这样一来，无需将私钥文件复制到WSL内，也能安全地通过认证。

9. 维护：膨胀的VHDX的优化（压缩）

WSL2最大的缺点之一就是其设计机制：“即使删除了Docker镜像或文件，Windows端的虚拟磁盘（.vhdx）的文件大小也不会自动缩小”。如果长时间进行开发，ext4.vhdx文件可能会膨胀到几十GB甚至几百GB。

为了释放磁盘空间，需要定期从Windows端对VHDX进行优化（Compact）。

首先，完全关闭WSL。
1

wsl --shutdown
以管理员权限打开PowerShell，执行以下 diskpart 命令，或使用Hyper-V模块的 Optimize-VHD 命令（仅在启用了Hyper-V的情况下才能使用后者）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 如果Hyper-V模块可用
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# 如果使用diskpart
diskpart
# 在以下提示符中进行交互式输入
DISKPART> select vdisk file="C:\Users\<用户名>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

定期执行此操作，可以收回C盘被白白浪费的容量。

10. 结语

WSL2已经完全超越了单纯“作为Windows上附赠的Linux”这一范畴，进化成了一个不亚于甚至超越macOS或原生Linux机器的强大开发平台。

只要全面应用本文所讲解的这些设置（通过 .wslconfig 进行资源优化、使用Zsh + Powerlevel10k增强终端、通过VS Code Remote实现透明访问，以及SSH集成和VHDX的维护），就能构建出一个零压力、高速且安全的“终极开发环境”。

虽然环境配置需要花费一点心思，但一旦设置妥当，毫无疑问将极大地提升您今后的工程生产力。请务必以本指南为基础，结合您自己的项目和喜好，探索出更多的定制可能。