1. WSL2

如何使用 WSL 在 Windows 上安装 Linux

简述安装方式如下：

1. 勾选使能 Windows 功能设置中的 适用于 Linux 的 Windows 子系统（即WSL - Windows Subsystem for Linux）以及 虚拟机平台 特性

   win+r运行optionalfeatures.exe，在弹出的 UI 界面中进行勾选后确定，按照提示等待电脑重启。

   

2. 下载安装 Linux 发行版

   打开微软商城搜索 WSL

   

   可以看到有一些可选的系统，可直接点击下载。

3. 可提前升级 WSL 的内核版本以避免在安装时出现各种问题：

   # 升级内核版本
   wsl --update
   

4. 常用 WSL 命令：

   # 查看当前已经安装的所有发行版系统
   wsl -l -v
   # 查看当前使用的默认发行版和内核版本
   wsl --status
   # 设置默认使用的Linux子系统
   wsl --set-default <Distro-Name>
   # 终止正在运行的子系统
   wsl --terminate <Distro-Name>
   # 强制终止所有正在运行的子系统
   wsl --shutdown -f
   

5. 使用 WSL 运行Shell程序：

   Windows 使用的CMD或PowerShell都不能直接运行 Linux 风格的Shell程序。一般情况下我们会使用Git-Bash在 Windows 系统上执行某些Shell程序，比如：

   # 使用git-bash执行一些基本的命令以及shell脚本
   Miku@TianYi~$ uname
   MINGW64_NT-10.0-22631
   Miku@TianYi~$ echo $SHELL
   /usr/bin/bash
   

   但是Git-Bash能运行的命令很有限，而且包管理很麻烦（ 和windows系统的包管理糅杂在一起 ）。此时在powershell中使用wsl命令则可以进行更加复杂的操作。在powershell中使用wsl命令时，系统会使用发行版内部环境的bash执行传递的命令，可在发行版中安装各种 Linux 系统上专属的软件来获得更好的体验，也可直接执行发行版上的Shell程序对本地的一些文件进行操作。

   # 使用WSL中的vim编辑本地文件（一般我会在WSL中配置一个插件齐全的VIM，这也是这种方式下我用的最多的命令）
   # 使用wsl命令时注意文件路径分隔符的转换
   PS C:\> wsl vim $(wsl wslpath -u "'$PWD'/tmp.ps1")
   

2. Docker-Desktop

2.1 Docker-Desktop 安装

官方网站地址：docker-desktop，可根据自己的系统类型下载对应版本：

我的电脑使用了一颗 Intel i7 芯片，故选择安装 AMD64 版本。安装时按照提示一路走下去即可，注意在 Configuration 界面**一定要勾选上`Use WSL 2 instead of Hyper-V (recommended)`**，且在安装前使用`wsl --update`将 WSL2 的内核升级到最新版本。

安装完成后来到设置界面，将 Ubuntu 设为默认的 WSL 集成。

2.2 镜像下载

docker pull命令可以从源拉取镜像到本地，但大家在使用时肯定会经常遇到类似：

miku@TianYi:~$ docker pull espressif/idf
Using default tag: latest
Error response from daemon: failed to resolve reference "docker.io/espressif/idf:latest": failed to do request: Head "https://registry-1.docker.io/v2/espressif/idf/manifests/latest": dialing registry-1.docker.io:443 container via direct connection because Docker Desktop has no HTTPS proxy: connecting to registry-1.docker.io:443:

很明显，此时要么使用魔法代理，要么使用国内公共的镜像网站（搞笑的是，docker专门给国内用户提供镜像服务的网站 Registry-Docker-CN 也不能正常访问。国内做镜像源服务的公司很多，可以自行搜索相关教程。这里提供一个我比较常用的网站：https://docker.aityp.com/，虽然渡渡鸟镜像同步站的镜像不够全，但也基本够用。

渡渡鸟镜像同步站页面：

搜索镜像后，选择想要的Tag，点击进入详情页后下拉可以找到拉取命令。

2.3 镜像使用

编写 Dockerfile 文件来构建本地镜像，通过 FROM 命令指定要使用的镜像：

# docker pull 命令无法正常执行时应该先将镜像下载到本地，再直接FROM本地镜像名
ARG IDF_VERSION=latest
FROM swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/espressif/idf:${IDF_VERSION}
xxxxx

通过docker pull从指定镜像站拉取镜像后，使用该镜像的 Docker Hub 官方源名称，通过docker tag为其创建别名。此举可使 Dockerfile 构建本地镜像时，FROM命令无需指定原拉取镜像站的地址，直接引用该别名即可，更方便迁移使用。

# 直接使用官方源名称espressif/idf
ARG IDF_VERSION=latest
FROM espressif/idf:${IDF_VERSION}
xxxxx

3. VSCode Required Extensions

3.1 ESP-IDF

在 VSCode 插件商城中搜索 ESP-IDF 即可直接下载安装该插件。官方文档写的非常详细：安装 ESP-IDF 和相关工具。下载安装完所有依赖后，即可通过 VSCode 命令来进行 ESP32 芯片相关项目的开发。

常用命令：

• 创建新项目：ESP-IDF: New Project
• ESP-IDF: Build Your Project：构建项目
• ESP-IDF: Select Port to Use (COM, tty, usbserial)：选择要使用的端口
• ESP-IDF: Select Monitor Port to Use (COM, tty, usbserial)：选择要使用的监视器端口
• ESP-IDF: Flash Your Project：烧录项目
• ESP-IDF: Run idf.py reconfigure Task：为项目生成compile_commands.json文件

部分常用命令直接集成到了侧边栏，可点击直接执行。

3.2 Dev Containers & Container Tools & WSL

Dev Containers & Container Tools & WSL 相当于是在 Windows 系统上通过 VSCode 编辑器在 Docker 容器内进行开发的所必须的插件全家桶了。

3.2.1 Dev Containers

在 VSCode 插件商城中搜索 Dev Containers 即可直接下载安装该插件。该插件相关的所有技术细节均可以在 Development Containers 中找到。

该插件使用由用户自定义的devcontainer.json配置文件来进行 统一、高效、可移植 的镜像、容器的构筑。核心思想为环境容器化，它将项目所需的编程语言（如 Go、Node.js）、工具链、依赖库甚至编辑器配置，全部封装在独立容器中。只要使用相同的devcontainer.json配置文件来拉起容器，就一定会能得到一个处处一致的标准化的容器（这个特性对于爱折腾环境的我太迷人了）。无论是个人或团队项目，本地开发或远程协作，都能显著提升标准环境管理的效率。注意：所有配置在 Github-Codespaces 中同样生效，具体请参考：Github-Codespaces

该插件也有一系列命令：

• 开发容器：添加开发容器配置文件…
  Dev Containers: Add Dev Container Configuration Files...
• 开发容器：打开容器配置文件
  Dev Containers: Open Container Configuration File
• 开发容器：在容器中重新打开（重新连接到容器）
  Dev Containers: Reopen in Container
• 开发容器：在容器中重新生成并重新打开（重构镜像，使用新镜像拉起容器并连接到容器）
  Dev Containers: Rebuild and Reopen in Container

3.2.2 Container Tools

在 VSCode 插件商城中搜索 Container Tools 即可直接下载安装该插件，开源仓库地址：Container Tools。该插件旨在为开发者提供在 VS Code 环境中便捷操作容器的功能，简化容器化应用的开发、调试和管理流程。

Container Tools 提供了一个强大的交互组件来管理容器、镜像、卷、网络等。比如可以简单直接的对一个容器进行Start, Stop, Attach Shell等操作，可以通过与 Dev Containers 的联动快速浏览一个卷内的文件。

3.2.3 WSL

微软官方介绍：

Visual Studio Code WSL 扩展可让您将 Windows Subsystem for Linux (WSL) 作为您全职开发环境，直接从 VS Code 使用。您可以开发基于 Linux 的环境，使用特定于 Linux 的工具链和实用程序，并且可以在 Windows 中舒适地运行和调试基于 Linux 的应用程序。

该扩展直接在 WSL 中运行命令和其他扩展，因此您可以编辑位于 WSL 或已挂载的 Windows 文件系统（例如 /mnt/c）中的文件，而无需担心路径问题、二进制兼容性或其他跨操作系统挑战。该扩展将在 WSL 中安装 VS Code Server；该服务器独立于 WSL 中现有的任何 VS Code 安装。

可以说有了 VSCode + WSL 就可以无感的在 Windows 系统上进行 Linux 相关的开发了。而且无论是 VSCode 还是 WSL 的内核，微软都是直接开源在 Github 上的。无需多言，微软的恩情还不完 \o/\o/\o/\o/

4. Run the Container

我们需要配置devcontainer.json以及Dockerfile文件。一般保存到本地项目根目录的.devcontainer文件夹下。可使用 VSCode 命令Dev Containers: Add Dev Container Configuration Files...添加官方预设的模板。

4.1 devcontainer.json

Dev Container CLI 提供了开发容器命令行工具，该工具可解析devcontainer.json配置文件，并基于此文件创建和配置开发容器。devcontainer.json的编写可参照：devcontainer.json reference。

我使用的 ESP-IDF 开发环境的devcontainer.json配置如下：

{
    // 此 devcontainer.json 的配置名称
    "name": "ESP-IDF",

    // 直接使用镜像构造时需通过 image 字段指定镜像名称，
    // 使用 Dockerfile 构造镜像时此字段用于指定 devcontainer 构建出的镜像名称
    "image": "esp-idf:release-v5.5",

    "build": {
        // 指定用于构建镜像的 Dockerfile 路径
        "dockerfile": "Dockerfile",
        // 构建镜像时传递的参数，此参数会被解析为数个 --build-arg <key>=<value>，
        // 若 Dockerfile 中使用 ARG 声明了 key 变量，则构建时使用 value 覆盖默认值
        "args": {
            // 可从 https://hub.docker.com/r/espressif/idf/tags 选取，
            // 为避免 latest 版本更新导致某些未知问题，此处特指定安装
            "IDF_VERSION": "release-v5.5"
        }
    },

    // 指定 docker run 时的附加参数
    "runArgs": [
        // "--privileged", // 允许容器内访问主机的全部设备
        "--device=/dev/esp32-s3-01:/dev/ttyACM0"
    ],

    // "postCreateCommand": "idf.py --version",
    // 指定需要在主机上进行的的初始化工作，避某些在容器上执行的耗时操作
    // "initializeCommand" : "",
    // 指定容器创建时需要执行的命令，仅执行一次
    // "postCreateCommand" : "chmod 666 /dev/esp32-s3-01", // 允许非 root 用户访问设备，但本例中默认为root用户，故注释掉
    // 指定每次容器启动都需要执行的命令
    // "postStartCommand" : "",
    // 指定每次 VSCode 连接时需要执行的命令
    "postAttachCommand" : "idf.py --version",

    
    // 预设 / 覆盖目标容器内的静态全局环境变量，
    // 若需更改项值需重新配置此字段之后重新拉起容器
    "containerEnv": {
        // ${localEnv:VARIABLE_NAME} 表示引用本地主机的环境变量 
        // 若引用的全局变量不存在则留空，或可通过 ${localEnv:VARIABLE_NAME:default_value} 来指定默认值
        "IDF_XTENSA_ELF_PATH": "/opt/esp/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/" // 设置交叉编译工具链路径为全局变量，供 C/C++ Intelligence 使用
    },

    // 官方解释：为支持 devcontainer.json 的服务/工具（或终端等子进程）设置或覆盖环境变量，但不会作用于整个容器
    // 容器拉起后，打开的 VSCode 的终端及内部扩展可以访问到 remoteEnv，修改项值无需重新拉起容器
    // "remoteEnv": {
    //     // 此配置支持使用本地环境变量以及containerEnv中的环境变量
    //     "TEST_VARIABLE_REMOTE": "${containerEnv:TEST_VARIABLE_CONTAINER}"
    // },

    // 指定容器运行时登录的用户
    // remoteUser 指定 VSCode 使用什么用户登入远程服务
    "remoteUser": "root",
    // containerUser 指定容器运行的默认用户，
    // devcontainer.json中未覆盖时默认为源镜像构建或 Dockerfile 中 USER 指令指定的用户
    "containerUser": "root",

    // 将本地工作目录通过绑定挂载到容器内，${localWorkspaceFolder}表示.devcontainer所在的上级目录
    // "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/,type=bind",
    // 使用卷挂载的方式则更加高效
    "workspaceMount": "source=DisplayDriverCode,target=/workspaces/,type=volume",

    // 容器内工作目录，容器拉起后会直接打开此文件夹
    "workspaceFolder": "/workspaces/", 

    "mounts": [
        "source=extensionCache,target=/root/.vscode-server/extensions,type=volume"  // 所有容器共享扩展的缓存
    ],

    // 容器拉起后 VSCode 在容器层的 settings 配置及要安装的扩展
    "customizations": {
        "vscode": {
            "settings": {
                "terminal.integrated.defaultProfile.linux": "bash",
                "idf.espIdfPath": "/opt/esp/idf",
                "idf.toolsPath": "/opt/esp",
                "idf.gitPath": "/usr/bin/git"
            },
            "extensions": [
                "espressif.esp-idf-extension",
                "ms-vscode.cpptools"
            ]
        }
    }
}

4.2 Dockerfile

Dockerfile的编写更不必多说，参考 ESP-IDF 提供的官方推荐Dockerfile格式：

ARG IDF_VERSION=latest
# 若 devcontainer.json 中配置了 "build.args.IDF_VERSION" 则覆盖 IDF_VERSION
FROM espressif/idf:${IDF_VERSION}

ENV LC_ALL=C.UTF-8
ENV LANG=C.UTF-8

# 预装必备软件
RUN apt-get update -y && apt-get install udev -y \
    minicom \
    lsof \
    vim \
    && rm -rf /var/lib/apt/lists/*

RUN echo "source /opt/esp/idf/export.sh > /dev/null 2>&1" >> ~/.bashrc

ENTRYPOINT [ "/opt/esp/entrypoint.sh" ]

CMD ["/bin/bash", "-c"]

4.3 Build & Run

建议：使用绑定挂载的方式可以简单的直接把工作目录映射到容器内，但我个人不建议这么做。一是绑定挂载的维护工作全由用户处理，本地增删都可能影响到容器的正常运行。二是 Docker 在 Windows 上并非原生运行，而是通过「宿主机→WSL2→Docker 容器」的三层架构实现，绑定挂载存在额外的文件共享损耗。使用卷的方式保存重要代码、资源文件，可以在不同的容器中直接复用，需要转移、拷贝文件时拉起一个Alpine容器cp一下即可。

两项配置文件都准备好后，执行 VSCode 命令Dev Containers: Rebuild and Reopen in Container，就可以在 VSCode 上连接到容器使用了。

连接到容器后，左下角会看到明显的标识。可执行一些指令来验证 devcontainer.json 文件的配置都被正确加载了。

5. Summary

整个开发环境的配置流程就是这些，安装好后就可以愉快 Coding 了~~~

ESP-IDF + VSCode / WSL / Docker-Desktop 这一套流程下来要学的新知识还真是不少，遇到的问题一部分是 VSCode 的配置方面的问题，另一部分就是各种插件配置文件的编写问题。下面列出我主要参考的各种文档：

1. Visual Studio Code 文档 - VSCode 编辑器
2. Visual Studio Code 文档 - 在容器内开发
3. Visual Studio Code 文档 - 开发容器 CLI
4. Visual Studio Code 文档 - WSL 教程
5. DockerDocs - Engine
6. Development Containers
7. Development Containers - Specification
8. ESP-IDF Extension for VSCode
9. 渡渡鸟镜像同布站

---

PS1: 个人能力有限，文档内容或有疏漏，恳请各位谅解。若文中存在不当之处，欢迎大家不吝指正，共同交流探讨。
PS2: ❤️❤️❤️MIKU宝宝真可爱❤️❤️❤️

歌曲分享：伊始