WSL2 + VSCode + C++ 后端开发环境搭建

0. 先看懂本文会用到什么

路径概念先搞懂

1. Linux 命令速查：先科普，再操作

下面这些命令会贯穿全文。初学者不要急着背，先知道它们“负责什么”。

常用 WSL 命令也要认识

2. 软件包与工具科普

这一节先把后面会安装的软件包讲清楚。知道它们是什么，排错时才不会慌。

基础 C++ 开发工具

后端项目依赖

3. 为什么选择 WSL2，而不是虚拟机或纯 Windows

• 目标是开发 Linux C++ 服务端，而不是 Windows 桌面程序；最终部署环境大概率也是 Ubuntu/Linux。
• WSL2 不需要 ISO 镜像、不需要 VirtualBox/VMware，也不需要完整 Linux 桌面，更适合轻量开发。
• 传统虚拟机更像一台完整电脑，但网络、共享目录、性能和配置复杂度会更高。
• Visual Studio 更偏 Windows C++、Win32、.NET、MFC；本项目需要 gcc、cmake、epoll、Redis、MySQL、Protobuf 等 Linux 生态，更推荐 VSCode + Remote WSL。

4. 进入正确工作目录

如果终端路径显示在 /mnt/c/WINDOWS/system32，说明你还在 Windows 文件系统里，不适合在这里写 Linux C++ 项目。

cd ~
pwd

正确结果应该类似：

/home/wqf

创建长期工作目录：

mkdir -p ~/workspace
cd ~/workspace

5. 修复 apt 404 问题并安装基础工具

5.1 处理 apt 404

如果遇到 404 Not Found，通常不是系统坏了，而是 apt 软件源索引过期。先清理并更新索引：

sudo apt clean
sudo apt update
sudo apt upgrade -y --fix-missing

如果仍然报 404，可以换成国内镜像源，例如阿里云镜像：

sudo sed -i 's|http://security.ubuntu.com/ubuntu|http://mirrors.aliyun.com/ubuntu|g' /etc/apt/sources.list
sudo sed -i 's|http://archive.ubuntu.com/ubuntu|http://mirrors.aliyun.com/ubuntu|g' /etc/apt/sources.list
sudo apt clean
sudo apt update
sudo apt upgrade -y

5.2 安装基础 C++ 开发工具

sudo apt install -y \
  build-essential \
  gdb \
  cmake \
  git \
  curl \
  wget \
  zip \
  unzip \
  pkg-config

5.3 验证基础工具

g++ --version
cmake --version
git --version

如果这些命令都能输出版本号，说明最基础的开发环境已经可用。

6. 安装 VSCode 插件并连接 WSL

6.1 安装插件

• Remote - WSL：让 VSCode 直接连接 WSL Ubuntu。
• C/C++：提供 C++ 语法高亮、补全、跳转和调试能力。
• CMake Tools：后续用 CMake 构建项目时更方便。
• CMake：提供 CMakeLists.txt 语法支持。

6.2 从 WSL 中打开 VSCode

cd ~/workspace
code .

第一次执行会安装 VSCode Server。成功后，VSCode 左下角应显示 WSL: Ubuntu-22.04。

6.3 打开终端

在 VSCode 顶部菜单点击“终端 → 新建终端”，或使用快捷键 Ctrl + `。终端里应看到类似：

wqf@DESKTOP:~/workspace$

这说明当前 VSCode 终端已经进入 Linux 环境。

7. 创建并运行第一个 C++ 程序

7.1 创建项目目录和文件

cd ~/workspace
mkdir echo-server
cd echo-server
touch main.cpp

mkdir 创建项目目录，touch 创建源文件。项目名 echo-server 可以对应后续的 Echo 信息流或 IM 后端项目。

7.2 写入 main.cpp

#include <iostream>

int main() {
  std::cout << "Echo Server started." << std::endl;
  return 0;
}

7.3 手动编译运行

g++ main.cpp -o app
./app

看到下面输出，就说明编译器、终端、文件系统和 VSCode 都能正常工作：

Echo Server started.

8. 引入 CMake：从玩具程序走向工程项目

真实 C++ 项目通常有多个源文件、头文件和第三方库。如果一直手写 g++ 命令，项目稍大就会失控，所以要尽早引入 CMake。

8.1 创建 CMakeLists.txt

touch CMakeLists.txt

写入以下内容：

cmake_minimum_required(VERSION 3.16)
project(echo-server)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(echo-server main.cpp)

8.2 用 CMake 构建

mkdir build
cd build
cmake ..
make
./echo-server

build 目录用于存放中间产物，保持项目根目录干净；cmake .. 生成构建配置，make 执行编译。

9. 整理项目结构

不要把所有代码都堆在 main.cpp。中型后端系统从一开始就应该建立清晰目录。

cd ~/workspace/echo-server
mkdir -p src include docs scripts
mv main.cpp src/main.cpp

推荐初始结构：

echo-server/
├── CMakeLists.txt
├── src/
│   └── main.cpp
├── include/
├── docs/
└── scripts/

修改 CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
project(echo-server)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(echo-server
  src/main.cpp
)

target_include_directories(echo-server PRIVATE include)

重新构建

rm -rf build
mkdir build
cd build
cmake ..
make
./echo-server

10. 安装后端项目所需依赖

基础环境跑通后，再安装 Protobuf、MySQL、Redis。不要一开始全堆上去，否则出错时很难定位。

sudo apt install -y \
  protobuf-compiler \
  libprotobuf-dev \
  mysql-server \
  redis-server \
  libmysqlclient-dev

验证 Protobuf

protoc --version

验证 Redis

sudo service redis-server start
redis-cli ping

如果返回：

PONG

说明 Redis 正常。

11. 为什么现在先不做 IM，以及后续路线

IM 长连接涉及 TCP、心跳、断线、连接映射、离线消息、ACK、Protobuf 编解码和并发安全，是项目中最复杂的模块之一。正确顺序是：先 HTTP，再数据库，再业务闭环，最后 TCP IM。

12. 当前阶段的验收标准

• VSCode 左下角显示 WSL: Ubuntu-22.04。
• 终端位于 /home/wqf/workspace 或其子目录，而不是 /mnt/c/...。
• g++ --version、cmake --version、git --version 都能输出版本。
• main.cpp 可以通过 g++ 编译并运行。
• CMakeLists.txt 可以成功生成 echo-server 可执行文件。
• redis-cli ping 可以返回 PONG。