环境搭建相关杂谈

欢迎你来读这篇博客，这篇博客主要是关于开发环境、AI 环境与常用工具搭建。

本文从一台相对干净的 Windows 电脑出发，整理 Windows、WSL2、Linux、Java、Node.js、Python、Docker、数据库、接口调试、设计与效率工具的安装和配置方式。

这不是一份“所有软件都必须安装”的购物清单，而是一份按开发方向选装、按项目版本落地、能够随时验证和卸载的环境搭建笔记。

序言

本文假设你具备基本的计算机操作经验，知道环境变量、终端、软件安装目录等基础概念，并对 Linux 命令有一定了解。

本文尽量还原完整步骤，但不会展开“点击下一步”“打开浏览器”一类基础操作。安装界面和软件版本会持续变化，涉及版本号、CUDA、驱动和镜像源时，应以对应软件的官方文档为准。

本文主要以以下环境为例：

宿主系统：Windows 11
Linux 环境：WSL2 + Ubuntu LTS
Java：JDK 21 为兼容主线，JDK 25 可用于新项目验证
Node.js：当前 LTS
Python：uv 或 Miniconda
容器：Docker Desktop + WSL2
AI：NVIDIA GPU + PyTorch

本文中的账号、密码、端口和镜像版本均为本地开发示例。生产环境不要直接照搬默认密码，更不要把密钥提交到 Git。

正文

一、先规划目录，再安装软件

环境搭建最容易出现的问题不是“不会安装”，而是软件散落、版本混乱、数据目录不明确。建议先统一目录。

Windows 示例：

D:\develop
├── environment       # JDK、Maven、Gradle 等运行环境
├── repository        # Maven、Gradle、npm 等本地缓存
├── workspace         # Windows 原生项目
├── software          # 安装包与便携软件
├── data              # 数据库或容器数据
├── backup            # WSL 导出、配置备份
└── scripts           # 环境检查与初始化脚本

WSL 示例：

/home/<user>
├── workspace         # Linux/WSL 项目
├── scripts
└── .config

1. 项目放在 Windows 还是 WSL

如果项目主要在 WSL 中编译和运行，建议放在：

1	`~/workspace`

不建议长期放在：

1	`/mnt/c/Users/<user>/workspace`

原因主要是 Linux 文件权限、软链接、大小写规则和大量小文件读写性能。Node.js 的 node_modules、Git 仓库和 Maven/Gradle 构建通常更适合放在 WSL 的 Linux 文件系统内。

如果项目完全使用 Windows 原生 JDK、Node.js 和 Python，则可以放在 D:\develop\workspace。

2. 不要重复安装同一套环境

常见重复安装包括：

Windows 安装一个 JDK，WSL 又安装一个 JDK；
Python 官方版、Microsoft Store、Anaconda、Miniconda、Pipenv 全部装一遍；
Windows 安装 Docker Desktop，WSL 里又手动安装 Docker Engine；
Node.js 官方安装包、NVM、fnm 同时管理 Node.js；
系统 Maven、IDEA 内置 Maven、Maven Wrapper 混用。

可以同时存在多套环境，但必须明确“哪个项目使用哪一套”，并学会使用以下命令定位当前环境：

where.exe java
where.exe python
where.exe node
where.exe git

which java
which python
which node
which git
type -a java

二、Windows 基础环境

1. 系统与硬件检查

查看 Windows 版本：

winver

查看系统架构：

1 2	`Get-CimInstance Win32_OperatingSystem \| Select-Object Caption, Version, OSArchitecture`

查看 CPU 是否开启虚拟化：

1 2	`Get-CimInstance Win32_Processor \| Select-Object Name, VirtualizationFirmwareEnabled, VMMonitorModeExtensions`

也可以在“任务管理器 → 性能 → CPU”中查看“虚拟化”状态。

查看显卡：

1 2	`Get-CimInstance Win32_VideoController \| Select-Object Name, DriverVersion`

如果虚拟化未开启，需要进入 BIOS/UEFI 开启 Intel VT-x、Intel Virtualization Technology 或 AMD-V/SVM。不同主板名称不同。

2. Windows Terminal

推荐使用 Windows Terminal 管理 PowerShell、CMD 和 WSL 标签页。

安装：

1	`winget install --id Microsoft.WindowsTerminal --exact`

验证：

1	`wt --version`

3. PowerShell 7

Windows 自带的 Windows PowerShell 5.1 可以保留，新脚本优先使用 PowerShell 7。

安装：

1	`winget install --id Microsoft.PowerShell --exact`

验证：

1	`pwsh --version`

查看 Profile：

1	`$PROFILE`

创建 Profile：

if (-not (Test-Path $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE -Force
}
notepad $PROFILE

4. WinGet

WinGet 是 Windows 官方包管理工具，一般随“应用安装程序”提供。

验证：

1 2	`winget --version winget source list`

更新软件源：

1	`winget source update`

搜索软件：

1	`winget search git`

查看软件详情：

1	`winget show --id Git.Git --exact`

安装、升级和卸载：

1
2
3

winget install --id Git.Git --exact
winget upgrade --all
winget uninstall --id Git.Git --exact

不要盲目复制第三方文章里的包 ID。先执行 winget search 或 winget show，确认发布者和安装源。

5. Scoop 与 Chocolatey

WinGet 已能满足大部分桌面软件安装。需要便携软件、开发命令行工具或自定义 Bucket 时，可以考虑 Scoop。

Scoop 更适合：

命令行工具；
无管理员权限安装；
软件集中存放；
多版本或便携软件。

Chocolatey 在企业脚本和历史环境中较常见。新机器不建议为了“包管理器齐全”同时安装 WinGet、Scoop 和 Chocolatey，选一到两个即可。

6. Windows 环境变量

查看当前 PATH：

1	`$env:Path -split ';'`

临时设置，仅当前终端有效：

1 2	`$env:JAVA_HOME = 'D:\develop\environment\jdk-21' $env:Path = "$env:JAVA_HOME\bin;$env:Path"`

永久写入当前用户环境变量：

[Environment]::SetEnvironmentVariable(
    'JAVA_HOME',
    'D:\develop\environment\jdk-21',
    'User'
)

追加用户 PATH 前先读取原值，不要直接覆盖：

$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$newPath = 'D:\develop\environment\apache-maven\bin'

if (($userPath -split ';') -notcontains $newPath) {
    [Environment]::SetEnvironmentVariable(
        'Path',
        "$userPath;$newPath",
        'User'
    )
}

7. PATH 过长与长路径问题

原文提到直接修改：

1	`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`

该位置确实保存系统环境变量，但应先清理重复和失效 PATH，再考虑直接编辑注册表。修改注册表前必须备份。

另外，PATH 过长和 Windows 传统的 260 字符文件路径限制不是一回事。

开启 Win32 长路径支持：

New-ItemProperty `
  -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' `
  -Name 'LongPathsEnabled' `
  -Value 1 `
  -PropertyType DWORD `
  -Force

该命令需要管理员权限，部分应用仍可能不支持长路径。

三、WSL2 安装 Ubuntu、迁移、备份与卸载

1. 安装 WSL2

使用管理员 PowerShell：

1	`wsl --install`

重启后检查：

1
2
3

wsl --version
wsl --status
wsl --list --verbose

更新 WSL：

1	`wsl --update`

查看可安装发行版：

1	`wsl --list --online`

安装 Ubuntu 时以列表中显示的名称为准，例如：

1	`wsl --install --distribution Ubuntu-24.04`

新机器优先选择仍处于支持周期内的 Ubuntu LTS。兼容性优先可以使用 Ubuntu 24.04 LTS；需要验证更新系统组件时，可以单独安装更新的 LTS 版本，不建议把所有项目一次性迁过去。

设置默认 WSL2：

1	`wsl --set-default-version 2`

设置默认发行版：

1	`wsl --set-default Ubuntu-24.04`

进入指定发行版：

1	`wsl --distribution Ubuntu-24.04`

2. 直接安装到指定目录

较新的 WSL 支持 --location 参数。先执行：

1	`wsl --help`

确认当前版本支持后，再使用：

1
2
3

wsl --install `
  --distribution Ubuntu-24.04 `
  --location D:\WSL\Ubuntu-24.04

如果当前 WSL 不支持该参数，使用下面的导出、注销和导入方式迁移。

3. 迁移 WSL 到 D 盘

先查看真实发行版名称：

1	`wsl --list --verbose`

关闭所有 WSL 实例：

1	`wsl --shutdown`

创建备份目录：

1 2	`New-Item -ItemType Directory -Path D:\WSL\backup -Force New-Item -ItemType Directory -Path D:\WSL\Ubuntu-AI -Force`

导出：

1	`wsl --export Ubuntu-24.04 D:\WSL\backup\ubuntu-24.04.tar`

确认备份文件存在且大小正常：

1	`Get-Item D:\WSL\backup\ubuntu-24.04.tar`

wsl --unregister 会删除当前发行版及其中的数据。没有确认备份可用之前，不要执行。

注销旧发行版：

1	`wsl --unregister Ubuntu-24.04`

导入：

wsl --import `
  Ubuntu-AI `
  D:\WSL\Ubuntu-AI `
  D:\WSL\backup\ubuntu-24.04.tar `
  --version 2

启动：

1	`wsl --distribution Ubuntu-AI`

导入后的发行版可能默认使用 root。在 WSL 中编辑：

1	`sudo nano /etc/wsl.conf`

写入：

1 2	`[user] default=your_username`

然后在 PowerShell 中执行：

1 2	`wsl --shutdown wsl --distribution Ubuntu-AI`

确认普通用户、Home 目录和文件均正常后，再删除备份压缩包。

4. 备份与恢复

日常备份：

1 2	`wsl --shutdown wsl --export Ubuntu-AI D:\WSL\backup\Ubuntu-AI-2026-07-16.tar`

恢复为新实例：

wsl --import `
  Ubuntu-AI-Restore `
  D:\WSL\Ubuntu-AI-Restore `
  D:\WSL\backup\Ubuntu-AI-2026-07-16.tar `
  --version 2

建议始终恢复成新名称，验证无误后再决定是否删除旧实例。

5. 卸载 WSL 发行版

查看名称：

1	`wsl --list --verbose`

关闭并注销：

1 2	`wsl --shutdown wsl --unregister Ubuntu-AI`

注销后再删除对应目录。不要直接删除正在注册的发行版目录。

6. WSL 资源限制

在 Windows 用户目录创建：

1	`C:\Users\<用户名>\.wslconfig`

示例：

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

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true

配置后执行：

1	`wsl --shutdown`

memory 和 processors 不宜抄固定值，应根据电脑内存、CPU 和 Docker/IDE 的实际占用调整。

7. 开启 systemd

在 WSL 中编辑：

1	`sudo nano /etc/wsl.conf`

写入：

[boot]
systemd=true

[user]
default=your_username

Windows PowerShell：

1	`wsl --shutdown`

重新进入后验证：

1 2	`systemctl status systemctl --version`

8. Ubuntu 初始化

更新软件：

1
2
3

sudo apt update
sudo apt full-upgrade -y
sudo apt autoremove -y

安装常用工具：

sudo apt install -y \
  build-essential \
  ca-certificates \
  curl \
  wget \
  git \
  unzip \
  zip \
  tar \
  vim \
  nano \
  tree \
  jq \
  gnupg \
  lsb-release \
  software-properties-common \
  net-tools \
  iputils-ping \
  dnsutils \
  htop

查看系统：

cat /etc/os-release
uname -a
lsb_release -a
df -h
free -h

设置时区：

1 2	`sudo timedatectl set-timezone Asia/Shanghai timedatectl`

9. Ubuntu 软件源

不要同时混用阿里、清华、华为、中科大等多个 Ubuntu 主仓库。混用镜像可能导致包索引和依赖版本不一致。

先查看代号：

1 2	`. /etc/os-release echo "$VERSION_CODENAME"`

Ubuntu 24.04 常见配置文件为：

1	`/etc/apt/sources.list.d/ubuntu.sources`

备份：

1
2
3

sudo cp \
  /etc/apt/sources.list.d/ubuntu.sources \
  /etc/apt/sources.list.d/ubuntu.sources.backup

将官方地址替换为清华镜像的示例：

sudo sed -i \
  -e 's|http://archive.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g' \
  -e 's|http://security.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g' \
  /etc/apt/sources.list.d/ubuntu.sources

更新：

1 2	`sudo apt clean sudo apt update`

恢复：

sudo cp \
  /etc/apt/sources.list.d/ubuntu.sources.backup \
  /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

Ubuntu 22.04 及更早版本常使用 /etc/apt/sources.list，操作前先查看实际文件，不要直接覆盖。

四、AI 环境

AI 环境可以分为三种路线：

flowchart TD
    A[开始搭建 AI 环境] --> B{是否使用 NVIDIA GPU}
    B -->|否| C[Python + CPU 版 PyTorch]
    B -->|是| D{在哪里运行}
    D -->|Windows 原生| E[Windows 驱动 + Python 环境]
    D -->|WSL2| F[Windows 驱动 + WSL2]
    E --> G{是否编译 CUDA 扩展}
    F --> G
    G -->|否| H[安装 PyTorch 官方 CUDA 构建]
    G -->|是| I[额外安装匹配的 CUDA Toolkit]

1. Python 环境选型

不要默认同时安装 Python 官方版、Anaconda、Miniconda、Pipenv、Poetry 和 uv。

推荐选择：

场景	推荐方案
普通 Python 项目	uv
Python 工具与脚本	uv
数据分析、科学计算	Miniconda
依赖大量 Conda 包	Miniconda
教学或简单入门	Python 官方安装包
已有 Poetry 项目	继续使用 Poetry
已有 Conda 环境文件	继续使用 Conda

2. Windows 使用 uv

安装：

1 2	powershell -ExecutionPolicy ByPass -c ` "irm https://astral.sh/uv/install.ps1 \| iex"

重新打开终端后验证：

1	`uv --version`

安装 Python：

1 2	`uv python list uv python install 3.13`

创建项目：

mkdir D:\develop\workspace\python-demo
cd D:\develop\workspace\python-demo

uv init
uv add requests
uv run python main.py

创建指定版本虚拟环境：

1	`uv venv --python 3.13`

激活：

1	`.venv\Scripts\Activate.ps1`

退出：

1	`deactivate`

3. WSL/Linux 使用 uv

安装：

1	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

重新加载 Shell：

1 2	`source ~/.bashrc uv --version`

安装 Python 和创建项目：

uv python install 3.13

mkdir -p ~/workspace/python-demo
cd ~/workspace/python-demo

uv init
uv add requests
uv run python main.py

4. Miniconda

Miniconda 比完整 Anaconda 更轻，只安装 Conda、Python 和少量基础依赖，需要什么再装什么。

WSL/Linux 示例：

cd /tmp

wget \
  https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

bash Miniconda3-latest-Linux-x86_64.sh

安装过程中阅读许可，选择安装目录，并决定是否执行 conda init。

重新打开终端后：

1 2	`conda --version conda info`

更新 Conda：

1	`conda update -n base -c defaults conda`

创建环境：

1 2	`conda create -n ai python=3.13 conda activate ai`

退出：

1	`conda deactivate`

查看和删除：

1 2	`conda env list conda remove -n ai --all`

如果是 ARM64 机器，不要下载 x86_64 安装包，应在官方页面选择对应架构。

5. NVIDIA 驱动

驱动安装在 Windows 宿主机。

官方入口：

通常：

游戏和新游戏优化优先：Game Ready Driver；
内容创作、稳定性和专业软件认证优先：Studio Driver。

两者都可以支持 CUDA。选择哪一个应看主要使用场景，不要因为“AI 环境”就认为只能使用 Studio Driver。

安装完成后，在 Windows PowerShell 检查：

1	`nvidia-smi`

重点关注：

Driver Version；
GPU 型号；
显存；
是否有异常进程；
命令能否正常识别显卡。

6. Driver、Toolkit、Runtime 与 cuDNN

这些概念不要混为一谈：

组件	作用
NVIDIA Driver	操作系统与显卡通信
CUDA Driver API	驱动提供的 CUDA 接口
CUDA Toolkit	`nvcc`、头文件、开发库、调试工具
CUDA Runtime	程序运行时依赖
cuDNN	深度神经网络常用 GPU 加速库
PyTorch CUDA 构建	PyTorch 官方打包的 CUDA 运行依赖

只运行 PyTorch 官方 CUDA 包时，通常不需要为了“看见 nvcc”而额外安装完整 Toolkit。

需要以下场景时才重点考虑 Toolkit：

编译 .cu 文件；
开发自定义 CUDA 程序；
编译 PyTorch CUDA Extension；
某个项目明确要求本机 CUDA Toolkit；
使用依赖 nvcc 的构建脚本。

7. Windows 原生 CUDA Toolkit

CUDA Toolkit 官方下载：

CUDA Toolkit Downloads

不要固定抄旧文章的 11.8、12.1 或其他版本。先确认：

显卡与驱动支持情况；
PyTorch、TensorFlow 或项目要求；
是否真的需要本机 Toolkit；
项目要求的编译器版本。

安装后验证：

1 2	`nvcc --version where.exe nvcc`

查看 CUDA 环境变量：

1 2	`$env:CUDA_PATH $env:Path -split ';' \| Select-String CUDA`

8. WSL2 使用 NVIDIA GPU

WSL2 的 GPU 支持依赖 Windows 宿主机驱动。不要在 WSL 中安装普通 Linux NVIDIA 显卡驱动覆盖宿主机提供的能力。

先在 Windows 中确认：

1
2
3

nvidia-smi
wsl --update
wsl --shutdown

再进入 WSL：

1	`nvidia-smi`

如果 WSL 中也能识别 GPU，说明基础映射正常。

只运行 PyTorch 时，可以直接创建 Python 环境并安装官方 CUDA 构建。

如果需要编译 CUDA 程序，再根据 NVIDIA 的 WSL-Ubuntu 安装页面安装 Toolkit。选择安装包时应选择：

1
2
3

Operating System: Linux
Architecture: x86_64
Distribution: WSL-Ubuntu

不要安装会尝试覆盖 Linux 显卡驱动的元包。每个 CUDA 版本的仓库命令不同，应复制 NVIDIA 官方页面实时生成的命令。

安装 Toolkit 后常见环境变量示例：

1
2
3

export CUDA_HOME=/usr/local/cuda
export PATH="$CUDA_HOME/bin:$PATH"
export LD_LIBRARY_PATH="$CUDA_HOME/lib64:${LD_LIBRARY_PATH:-}"

写入 ~/.bashrc：

cat >> ~/.bashrc <<'EOF'

# CUDA Toolkit
export CUDA_HOME=/usr/local/cuda
export PATH="$CUDA_HOME/bin:$PATH"
export LD_LIBRARY_PATH="$CUDA_HOME/lib64:${LD_LIBRARY_PATH:-}"
EOF

source ~/.bashrc

验证：

1
2
3

nvcc --version
nvidia-smi
ls -l /usr/local/cuda

如果 nvidia-smi 正常、nvcc 不存在，只能说明没有安装 Toolkit，不能直接判断 PyTorch GPU 不可用。

9. 安装 PyTorch

PyTorch 安装命令会随版本和受支持 CUDA 构建变化，建议始终从官方选择器生成：

PyTorch Start Locally

选择：

操作系统；
包管理器；
Python；
Compute Platform。

CPU 环境示例：

uv venv --python 3.13
source .venv/bin/activate

uv pip install \
  torch \
  torchvision \
  torchaudio \
  --index-url https://download.pytorch.org/whl/cpu

GPU 环境不要随便把示例中的 cuXXX 当真实地址。将官方选择器生成的命令复制到当前虚拟环境中执行。

如果官方生成的是：

1	`pip install ...`

也可以在 uv 虚拟环境中使用：

1	`uv pip install ...`

或者直接使用官方命令，关键是确认命令执行的 Python 与当前环境一致：

1
2
3

which python
python --version
python -m pip --version

10. PyTorch GPU 验证脚本

创建 check_torch.py：

from __future__ import annotations

import sys

import torch


def main() -> None:
    print(f"Python: {sys.version}")
    print(f"PyTorch: {torch.__version__}")
    print(f"PyTorch CUDA runtime: {torch.version.cuda}")
    print(f"CUDA available: {torch.cuda.is_available()}")
    print(f"cuDNN available: {torch.backends.cudnn.is_available()}")
    print(f"cuDNN version: {torch.backends.cudnn.version()}")

    if not torch.cuda.is_available():
        print("当前 PyTorch 未检测到可用 CUDA GPU。")
        return

    device = torch.device("cuda")
    print(f"GPU count: {torch.cuda.device_count()}")
    print(f"Current GPU: {torch.cuda.current_device()}")
    print(f"GPU name: {torch.cuda.get_device_name(device)}")

    left = torch.randn((2048, 2048), device=device)
    right = torch.randn((2048, 2048), device=device)
    result = left @ right

    torch.cuda.synchronize()
    print(f"Matrix result device: {result.device}")
    print("GPU matrix multiplication passed.")


if __name__ == "__main__":
    main()

运行：

1	`python check_torch.py`

11. 常见 AI 环境问题

`nvidia-smi` 正常，但 `torch.cuda.is_available()` 为 `False`

检查：

1 2	`python -c "import sys; print(sys.executable)" python -c "import torch; print(torch.__version__, torch.version.cuda)"`

常见原因：

装成了 CPU 版 PyTorch；
IDE 使用了另一个 Python；
激活环境后又使用了全局 pip；
新显卡需要更新的 PyTorch 构建；
WSL 或显卡驱动过旧。

`nvcc` 不存在

如果只是运行 PyTorch，不一定需要处理。

如果项目需要编译 CUDA Extension，再安装兼容 Toolkit。

cuDNN 手动复制后冲突

不建议默认使用以下旧式思路：

1	`把 cuDNN 的 include 和 lib 文件全部复制到 /usr/local/cuda`

这样容易让系统库、Conda 库、PyTorch 自带库相互覆盖。除非项目明确要求手动部署，否则优先使用官方包管理方式。

五、通用开发工具

1. Git

Windows 安装：

1	`winget install --id Git.Git --exact`

WSL 安装：

1 2	`sudo apt update sudo apt install -y git`

验证：

1	`git --version`

全局配置：

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global fetch.prune true
git config --global pull.rebase false

Windows 原生 Git：

1	`git config --global core.autocrlf true`

WSL/Linux：

1	`git config --global core.autocrlf input`

查看配置来源：

1	`git config --list --show-origin`

SSH Key

生成：

1	`ssh-keygen -t ed25519 -C "you@example.com"`

启动 Agent：

1 2	`eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519`

查看公钥：

1	`cat ~/.ssh/id_ed25519.pub`

测试 GitHub：

1	`ssh -T git@github.com`

GitHub、GitLab、Gitee 多账号

创建不同密钥：

1 2	`ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_github -C "github@example.com" ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_gitlab -C "gitlab@example.com"`

编辑 ~/.ssh/config：

Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes

Host gitlab-company
    HostName gitlab.example.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitlab
    IdentitiesOnly yes

克隆：

1	`git clone git@github-personal:your-name/project.git`

修复权限：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519_*
chmod 644 ~/.ssh/*.pub

2. 代码托管平台

GitHub：开源生态、Actions、Packages、Code Review；
GitLab：自托管、DevOps 平台、CI/CD；
Gitee：国内访问和企业协作；
企业内部平台：应优先遵守公司的权限、分支和密钥管理规范。

不要把 Git、GitHub、GitLab、Gitee 当成同一类软件：

Git 是版本控制工具；
GitHub/GitLab/Gitee 是托管和协作平台。

3. 终端和远程管理

工具	主要用途
Windows Terminal	本地多终端
PowerShell 7	Windows 自动化
OpenSSH	SSH 客户端与服务端
MobaXterm	SSH、SFTP、X11 等集成
Tabby	跨平台终端
WinSCP	SFTP/SCP 文件传输
JumpServer	企业堡垒机
1Panel/宝塔	可视化服务器运维

服务器管理优先掌握 SSH 和系统命令。面板工具可以提高效率，但不要用面板代替 Linux 基础能力。

4. Web 服务器和应用服务器

工具	定位
Nginx	反向代理、静态资源、负载均衡
Apache HTTP Server	通用 Web Server
Caddy	自动 HTTPS、配置简洁
Tomcat	Java Servlet 容器
Spring Boot 内嵌容器	Java 应用常见运行方式

Spring Boot 项目通常直接使用内嵌 Tomcat、Jetty 或 Undertow，不需要为了“Java 环境完整”额外安装一套系统 Tomcat。

六、容器环境

1. Docker Desktop

Windows 安装：

1	`winget install --id Docker.DockerDesktop --exact`

安装后在 Docker Desktop 中确认：

Settings
└── General
    └── Use the WSL 2 based engine

Settings
└── Resources
    └── WSL Integration
        └── 启用目标 Ubuntu 发行版

不要在同一个 WSL 发行版里同时安装另一套 Docker Engine，除非明确知道自己在隔离什么。

验证：

docker version
docker info
docker compose version
docker run --rm hello-world

2. Docker 数据位置

容器、镜像和卷会持续占用磁盘。应定期查看：

docker system df
docker image ls
docker volume ls
docker container ls -a

清理未使用资源：

1	`docker system prune`

清理所有未使用镜像：

1	`docker system prune -a`

清理未使用卷：

1	`docker volume prune`

执行清理前先确认数据是否仍需要。数据库数据放在匿名卷里时，误删卷可能直接丢数据。

3. 本地数据库 Docker Compose

创建目录：

1 2	`mkdir -p ~/workspace/local-dev cd ~/workspace/local-dev`

创建 .env：

MYSQL_ROOT_PASSWORD=local_mysql_root
MYSQL_DATABASE=demo
MYSQL_USER=demo
MYSQL_PASSWORD=local_mysql_password

POSTGRES_DB=demo
POSTGRES_USER=demo
POSTGRES_PASSWORD=local_postgres_password

REDIS_PASSWORD=local_redis_password

RABBITMQ_DEFAULT_USER=demo
RABBITMQ_DEFAULT_PASS=local_rabbitmq_password

创建 compose.yaml：

name: local-dev

services:
  mysql:
    image: mysql:8.4
    container_name: local-mysql
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_0900_ai_ci
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "mysqladmin ping -h 127.0.0.1 -uroot -p$${MYSQL_ROOT_PASSWORD}"
        ]
      interval: 10s
      timeout: 5s
      retries: 10

  postgres:
    image: postgres:17-alpine
    container_name: local-postgres
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"
        ]
      interval: 10s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7.4-alpine
    container_name: local-redis
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command:
      - redis-server
      - --appendonly
      - "yes"
      - --requirepass
      - ${REDIS_PASSWORD}
    healthcheck:
      test:
        [
          "CMD",
          "redis-cli",
          "-a",
          "${REDIS_PASSWORD}",
          "ping"
        ]
      interval: 10s
      timeout: 5s
      retries: 10

  rabbitmq:
    image: rabbitmq:4-management
    container_name: local-rabbitmq
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_DEFAULT_USER}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_DEFAULT_PASS}
    ports:
      - "5672:5672"
      - "15672:15672"
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    healthcheck:
      test:
        [
          "CMD",
          "rabbitmq-diagnostics",
          "-q",
          "ping"
        ]
      interval: 10s
      timeout: 5s
      retries: 10

volumes:
  mysql-data:
  postgres-data:
  redis-data:
  rabbitmq-data:

启动：

1	`docker compose up -d`

查看状态：

1 2	`docker compose ps docker compose logs -f`

停止但保留数据：

1	`docker compose down`

停止并删除卷：

1	`docker compose down -v`

本例版本只是可复现示例。实际项目应根据生产环境锁定数据库大版本，不要因为镜像有更新就直接跨大版本升级。

4. Kubernetes 与 CRI

CRI、containerd、CRI-O 主要用于 Kubernetes 节点运行时，不是普通桌面开发者必须安装的“容器工具”。

本机开发通常选择：

Docker Desktop；
Podman Desktop；
Rancher Desktop；
Minikube；
Kind；
Docker Desktop Kubernetes。

需要搭建 Kubernetes 集群时，再单独规划 containerd、CNI、Ingress、存储和高可用，不建议把它们挤进基础工作站安装步骤。

七、前端开发环境

1. Node.js 版本管理

推荐使用版本管理器，而不是长期依赖单个 Node.js 安装包。

fnm 支持 Windows、Linux 和 macOS。

Windows 安装：

1	`winget install Schniz.fnm`

配置 PowerShell Profile：

if (-not (Test-Path $PROFILE)) {
    New-Item $PROFILE -Force
}

Add-Content $PROFILE `
  'fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression'

重新打开 PowerShell，安装 LTS：

fnm install --lts
fnm use --lts
node --version
npm --version

WSL/Linux：

1	`curl -fsSL https://fnm.vercel.app/install \| bash`

确保 ~/.bashrc 中包含：

1	`eval "$(fnm env --use-on-cd --shell bash)"`

重新加载：

1
2
3

source ~/.bashrc
fnm install --lts
fnm use --lts

项目锁定版本：

1	`node --version > .node-version`

2. npm、pnpm、Yarn 与 Corepack

npm 随 Node.js 安装。

查看：

1	`npm --version`

启用 Corepack：

1	`corepack enable`

安装并激活 pnpm：

1 2	`corepack prepare pnpm@latest --activate pnpm --version`

一个项目只应提交一种锁文件：

npm：package-lock.json
pnpm：pnpm-lock.yaml
Yarn：yarn.lock

不要混用三个包管理器，然后把三个锁文件一起提交。

3. nrm

需要在多个 npm Registry 间切换时可以使用：

1 2	`npm install -g nrm nrm ls`

添加企业仓库：

1 2	`nrm add company https://npm.example.com/ nrm use company`

如果团队统一使用 .npmrc，优先提交项目级配置，不要只依赖个人机器上的 nrm 状态。

4. VS Code

安装：

1	`winget install --id Microsoft.VisualStudioCode --exact`

常用扩展按需选择：

WSL
Dev Containers
Docker
ESLint
Prettier
Vue - Official
Java Extension Pack
Python
GitLens

从 WSL 打开项目：

1 2	`cd ~/workspace/project code .`

5. WebStorm 与 HBuilderX

WebStorm：适合大型 JavaScript、TypeScript、Vue、React 工程；
VS Code：扩展灵活、启动快；
HBuilderX：适合 uni-app 和 DCloud 生态；
微信开发者工具：微信小程序必须；
Android Studio：Android、Flutter 和部分跨端工具链需要。

没有必要把所有 IDE 都装上。根据当前技术栈选择主 IDE 和一个轻量编辑器即可。

6. 创建 Vite 项目验证

mkdir -p ~/workspace
cd ~/workspace

pnpm create vite frontend-demo
cd frontend-demo

pnpm install
pnpm dev

构建验证：

1	`pnpm build`

八、Java 后端开发环境

1. JDK 发行版选择

常见 JDK 发行版：

Eclipse Temurin
Oracle JDK
Microsoft Build of OpenJDK
Amazon Corretto
Azul Zulu
GraalVM

普通 Java 后端开发可以优先选择 Eclipse Temurin 等 OpenJDK 发行版。具体选择还应遵守公司运行环境、许可证和生产镜像规范。

2. Windows 安装 JDK

使用 WinGet 搜索：

1	`winget search Temurin`

确认需要的版本和包 ID 后安装：

1	`winget install --id <搜索得到的精确包ID> --exact`

安装后验证：

1
2
3

java -version
javac -version
where.exe java

查看 JAVA_HOME：

1	`$env:JAVA_HOME`

如果手动安装，设置：

[Environment]::SetEnvironmentVariable(
    'JAVA_HOME',
    'D:\develop\environment\jdk-21',
    'User'
)

PATH 添加：

1	`%JAVA_HOME%\bin`

不要在 PATH 中同时放多个 JDK 的 bin 目录。

3. WSL 使用 SDKMAN

安装依赖：

1	`sudo apt install -y curl zip unzip`

安装 SDKMAN：

1	`curl -s "https://get.sdkman.io" \| bash`

加载：

1 2	`source "$HOME/.sdkman/bin/sdkman-init.sh" sdk version`

查看可安装 JDK：

1	`sdk list java`

安装时从列表中选择对应的 Temurin 标识：

1	`sdk install java <identifier>`

查看：

1
2
3

sdk current java
java -version
javac -version

临时切换：

1	`sdk use java <identifier>`

设置默认：

1	`sdk default java <identifier>`

项目级版本可以使用 .sdkmanrc：

1	`sdk env init`

编辑 .sdkmanrc 后启用：

sdk env

4. Maven

WSL 使用 SDKMAN：

1 2	`sdk install maven mvn -version`

Windows 可以从 Maven 官方下载二进制包，解压到：

1	`D:\develop\environment\apache-maven`

设置：

1 2	`MAVEN_HOME=D:\develop\environment\apache-maven PATH=%MAVEN_HOME%\bin`

验证：

1	`mvn -version`

Maven 本地仓库

Windows：

1	`D:\develop\repository\maven`

WSL：

1	`~/.m2/repository`

用户配置文件：

1 2	`Windows: %USERPROFILE%\.m2\settings.xml Linux: ~/.m2/settings.xml`

示例：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
            http://maven.apache.org/SETTINGS/1.2.0
            https://maven.apache.org/xsd/settings-1.2.0.xsd">

    <!-- Windows 示例：
    <localRepository>D:/develop/repository/maven</localRepository>
    -->

    <interactiveMode>true</interactiveMode>
    <offline>false</offline>

    <mirrors>
        <!-- 企业环境优先替换为 Nexus 或 Artifactory 私服。 -->
        <mirror>
            <id>aliyun-public</id>
            <name>Aliyun Maven Public</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>

    <profiles>
        <profile>
            <id>default-jdk</id>
            <properties>
                <maven.compiler.release>21</maven.compiler.release>
                <project.build.sourceEncoding>
                    UTF-8
                </project.build.sourceEncoding>
            </properties>
        </profile>
    </profiles>

    <activeProfiles>
        <activeProfile>default-jdk</activeProfile>
    </activeProfiles>
</settings>

验证有效配置：

1	`mvn help:effective-settings`

如果公司已有 Nexus 或 Artifactory，应使用公司私服，并把认证信息放在个人 settings.xml 或安全凭据系统中，不要提交到项目仓库。

Maven Wrapper

项目中优先使用 Wrapper：

1	`mvn wrapper:wrapper`

生成后：

1 2	`./mvnw -version ./mvnw clean verify`

Windows：

1	`.\mvnw.cmd clean verify`

Wrapper 可以让团队使用项目指定的 Maven 版本。

5. Gradle

WSL 使用 SDKMAN：

1 2	`sdk install gradle gradle --version`

项目应优先使用 Gradle Wrapper：

1 2	`gradle wrapper ./gradlew build`

不要要求团队成员都手工安装完全相同的全局 Gradle。

6. IntelliJ IDEA

安装方式：

JetBrains Toolbox；
IDEA 官方安装包；
WinGet 搜索后安装。

建议配置：

Project SDK        → 项目指定 JDK
Maven home path    → Wrapper 或指定 Maven
Gradle JVM         → 项目指定 JDK
File Encoding      → UTF-8
Line Separator     → LF
Terminal           → PowerShell 或 WSL
Git executable     → 与项目环境一致

如果项目放在 WSL：

从 IDEA 打开 \\wsl$\发行版\home\用户\workspace；
使用 WSL JDK；
使用 WSL Maven/Gradle；
Terminal 选择 WSL；
不要让 Windows Maven 去构建 WSL 内的 Linux 路径。

7. Spring Boot 环境验证

在 WSL 中创建项目：

mkdir -p ~/workspace
cd ~/workspace

curl -G https://start.spring.io/starter.zip \
  --data-urlencode type=maven-project \
  --data-urlencode language=java \
  --data-urlencode baseDir=environment-demo \
  --data-urlencode groupId=com.example \
  --data-urlencode artifactId=environment-demo \
  --data-urlencode name=environment-demo \
  --data-urlencode packageName=com.example.environmentdemo \
  --data-urlencode javaVersion=21 \
  --data-urlencode dependencies=web \
  --output environment-demo.zip

unzip environment-demo.zip
cd environment-demo

运行测试：

1	`./mvnw test`

启动：

1	`./mvnw spring-boot:run`

另一个终端访问：

1	`curl -i http://localhost:8080`

如果返回 404，说明 Web Server 已启动，只是还没有定义接口。

创建控制器：

package com.example.environmentdemo;

import java.util.Map;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class EnvironmentController {

    @GetMapping("/environment")
    public Map<String, Object> environment() {
        return Map.of(
            "status", "ok",
            "javaVersion", System.getProperty("java.version"),
            "os", System.getProperty("os.name")
        );
    }
}

再次访问：

1	`curl http://localhost:8080/environment`

九、Python、Go、PHP 与 .NET 开发环境

1. Python 开发工具

PyCharm：完整 Python IDE；
VS Code：轻量，配合 Python 与 Jupyter 扩展；
JupyterLab：数据分析与实验记录；
uv：Python、虚拟环境与依赖管理；
Miniconda：科学计算和 Conda 生态。

安装 JupyterLab：

1 2	`uv tool install jupyterlab jupyter lab`

或者项目内：

1 2	`uv add jupyterlab uv run jupyter lab`

2. Go

从官方页面选择对应平台：

Go Downloads

安装后验证：

1 2	`go version go env`

创建项目：

mkdir -p ~/workspace/go-demo
cd ~/workspace/go-demo

go mod init example.com/go-demo

main.go：

package main

import "fmt"

func main() {
	fmt.Println("Go environment is ready.")
}

运行：

1	`go run .`

网络环境需要时可以配置代理：

1	`go env -w GOPROXY=https://goproxy.cn,direct`

公司环境应优先使用公司内部代理，不要把个人代理配置写进公共脚本。

IDE：

GoLand；
VS Code + Go 扩展。

3. PHP

Windows 本地一体化开发可以选择 PHPStudy 等集成环境；更可控的方式是使用 Docker。

基本工具：

PHP；
Composer；
PhpStorm；
Nginx/Apache；
MySQL/PostgreSQL。

验证：

1 2	`php -v composer --version`

4. .NET

安装 .NET SDK：

.NET Downloads

验证：

1 2	`dotnet --info dotnet --list-sdks`

创建项目：

1
2
3

dotnet new webapi -n DotnetDemo
cd DotnetDemo
dotnet run

IDE：

Visual Studio；
JetBrains Rider；
VS Code + C# 扩展。

十、数据库开发环境

1. 数据库服务推荐方式

本地开发优先使用 Docker，除非：

需要 Windows 服务形式常驻；
需要测试特定安装器行为；
数据量大且需要原生磁盘调优；
软件许可证或驱动限制；
公司明确规定本机安装方式。

常用数据库：

数据库	默认端口	常见用途
MySQL	3306	Web、业务系统
PostgreSQL	5432	通用关系型、复杂查询
Redis	6379	缓存、锁、队列
MongoDB	27017	文档数据库
SQL Server	1433	Microsoft 生态
Oracle	1521	企业核心系统

2. 数据库客户端

工具	特点
DataGrip	JetBrains 生态、数据库支持丰富
DBeaver	跨平台、社区版可用
Navicat	图形化体验成熟
MySQL Workbench	MySQL 官方工具
pgAdmin	PostgreSQL 官方管理工具
RedisInsight	Redis 可视化
MongoDB Compass	MongoDB 官方客户端

开发机无需为每个数据库安装一个客户端。DataGrip 或 DBeaver 通常可以覆盖主要关系型数据库。

3. 数据库建模

PowerDesigner：传统企业数据库建模；
Enterprise Architect：UML、架构与建模；
draw.io：轻量架构图；
ProcessOn：在线协作；
dbdiagram.io：文本化 ER 图；
MySQL Workbench：MySQL 模型。

推荐把可维护的结构定义放在：

Flyway/Liquibase 迁移脚本；
SQL DDL；
DBML；
Mermaid ER Diagram；
版本库中的设计文档。

不要只保留一份无法追踪历史的图片。

十一、接口调试、抓包与网络工具

1. 接口调试

工具	适用场景
Apifox	API 设计、文档、Mock、调试、测试
Postman	API 调试与集合生态
Bruno	Git 友好的本地 API 集合
Insomnia	REST、GraphQL 调试
curl	命令行与自动化
HTTPie	更易读的 HTTP CLI

curl 示例：

curl -i \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name":"Mario"}' \
  http://localhost:8080/api/users

2. 抓包与代理

工具	适用场景
Wireshark	网络数据包分析
Fiddler Classic/Everywhere	HTTP(S) 抓包
Charles	跨平台 HTTP(S) 代理
Proxyman	macOS 抓包
mitmproxy	命令行与脚本化代理

HTTPS 抓包会安装本地 CA 证书。使用后应确认信任范围，不要把个人代理证书装到不受控的生产机器。

十二、设计、原型与文档工具

1. 原型与设计

Axure：复杂交互原型；
Figma：UI 设计与多人协作；
墨刀：国内产品原型；
蓝湖：设计稿交付、标注与协作；
PxCook：设计标注；
draw.io：架构和流程图；
Excalidraw：手绘风格草图；
ProcessOn：在线流程图。

2. 文本与知识管理

工具	主要用途
Typora	Markdown 写作
Obsidian	本地知识库
Notion	云端协作
VS Code	代码和文本
Notepad++	Windows 轻量文本
Typst	技术排版
WPS/Microsoft 365	办公文档
Zotero	文献管理

技术博客建议：

Markdown 文件纳入 Git；
图片单独放资源目录；
Mermaid 图保留源码；
引用链接尽量使用官方文档；
命令注明操作系统和 Shell；
涉及版本时注明写作日期。

十三、常用效率工具

下面是按需选择，不是必须全部安装。

1. 搜索和文件预览

Everything：Windows 文件搜索；
PowerToys Run：启动器；
QuickLook：空格预览文件；
Listary：文件搜索与快速跳转。

2. 截图和录屏

Snipaste：截图、贴图；
ShareX：截图和自动化；
ScreenToGif：GIF 录制；
OBS Studio：录屏和直播；
Bandicam：屏幕录制。

3. 压缩和媒体

7-Zip；
Bandizip；
PotPlayer；
VLC。

4. Windows 增强

Microsoft PowerToys；
Ditto 剪贴板；
TrafficMonitor；
AutoHotkey。

WinGet 示例：

1 2	`winget install --id Microsoft.PowerToys --exact winget install --id 7zip.7zip --exact`

安装前仍建议执行 winget show 检查软件来源。

十四、推荐安装顺序

不需要一天之内把所有软件装完。建议按照当前工作需要逐层搭建。

flowchart TD
    A[Windows 更新与驱动] --> B[Terminal + PowerShell + WinGet]
    B --> C[Git + SSH]
    C --> D[WSL2 + Ubuntu]
    D --> E{主要开发方向}
    E -->|Java| F[JDK + Maven/Gradle + IDEA]
    E -->|前端| G[fnm + Node.js + pnpm + VS Code/WebStorm]
    E -->|Python/AI| H[uv/Miniconda + PyTorch]
    F --> I[Docker Desktop]
    G --> I
    H --> I
    I --> J[数据库与中间件]
    J --> K[接口调试与辅助工具]

建议顺序：

完成 Windows 更新和硬件驱动；
安装 Terminal、PowerShell 和包管理工具；
安装 Git，配置 SSH；
安装 WSL2 和 Ubuntu；
根据开发方向安装 JDK、Node.js、Python；
安装 IDE；
安装 Docker Desktop；
使用 Compose 启动数据库和中间件；
创建最小项目验证；
最后再安装设计、抓包和效率工具；
需要 AI GPU 时，再配置驱动、PyTorch 和可选 Toolkit。

十五、一键安装与环境检查脚本

1. Windows 常用工具安装脚本

创建 install-dev-tools.ps1：

$ErrorActionPreference = 'Stop'

$packages = @(
    'Microsoft.WindowsTerminal',
    'Microsoft.PowerShell',
    'Git.Git',
    'Microsoft.VisualStudioCode',
    'Docker.DockerDesktop',
    'Microsoft.PowerToys',
    '7zip.7zip'
)

foreach ($package in $packages) {
    Write-Host "Checking $package ..." -ForegroundColor Cyan

    $installed = winget list --id $package --exact 2>$null |
        Select-String $package

    if ($installed) {
        Write-Host "[SKIP] $package is installed." `
            -ForegroundColor Yellow
        continue
    }

    Write-Host "[INSTALL] $package" -ForegroundColor Green

    winget install `
        --id $package `
        --exact `
        --accept-package-agreements `
        --accept-source-agreements
}

运行：

1 2	`Set-ExecutionPolicy -Scope Process Bypass .\install-dev-tools.ps1`

包 ID 可能随仓库调整。脚本执行失败时先运行：

1	`winget search <软件名>`

2. WSL 初始化脚本

创建 init-wsl.sh：

#!/usr/bin/env bash

set -Eeuo pipefail

log() {
  printf '\n\033[1;34m==> %s\033[0m\n' "$1"
}

log "Updating APT packages"
sudo apt update
sudo apt full-upgrade -y

log "Installing common development packages"
sudo apt install -y \
  build-essential \
  ca-certificates \
  curl \
  wget \
  git \
  unzip \
  zip \
  tar \
  vim \
  nano \
  tree \
  jq \
  gnupg \
  lsb-release \
  net-tools \
  iputils-ping \
  dnsutils \
  htop

log "Creating workspace"
mkdir -p "$HOME/workspace" "$HOME/scripts"

log "Environment summary"
printf 'User: %s\n' "$USER"
printf 'Home: %s\n' "$HOME"
printf 'Shell: %s\n' "$SHELL"

git --version
curl --version | head -n 1

log "WSL initialization completed"

授权并运行：

1 2	`chmod +x init-wsl.sh ./init-wsl.sh`

3. 开发环境检查脚本

创建 check-dev-env.sh：

#!/usr/bin/env bash

set -u

pass() {
  printf '\033[32m[PASS]\033[0m %-18s %s\n' "$1" "$2"
}

warn() {
  printf '\033[33m[WARN]\033[0m %-18s %s\n' "$1" "$2"
}

check_command() {
  local name="$1"
  local command_name="$2"
  local version_command="$3"

  if command -v "$command_name" >/dev/null 2>&1; then
    local version
    version="$(eval "$version_command" 2>&1 | head -n 1)"
    pass "$name" "$version"
  else
    warn "$name" "not installed"
  fi
}

check_command "Git" "git" "git --version"
check_command "Java" "java" "java -version"
check_command "Javac" "javac" "javac -version"
check_command "Maven" "mvn" "mvn -version"
check_command "Gradle" "gradle" "gradle --version"
check_command "Node.js" "node" "node --version"
check_command "npm" "npm" "npm --version"
check_command "pnpm" "pnpm" "pnpm --version"
check_command "Python" "python" "python --version"
check_command "uv" "uv" "uv --version"
check_command "Conda" "conda" "conda --version"
check_command "Docker" "docker" "docker --version"
check_command "Compose" "docker" "docker compose version"
check_command "NVIDIA GPU" "nvidia-smi" \
  "nvidia-smi --query-gpu=name,driver_version --format=csv,noheader"
check_command "CUDA Toolkit" "nvcc" "nvcc --version"
check_command "Go" "go" "go version"
check_command ".NET" "dotnet" "dotnet --version"

执行：

1 2	`chmod +x check-dev-env.sh ./check-dev-env.sh`

某项显示 WARN 不一定代表环境有问题。例如：

不做 CUDA 编译时，可以没有 nvcc；
Maven 项目使用 Wrapper 时，可以不安装全局 Maven；
不写 Go 项目时，不需要安装 Go；
不使用 Conda 时，只安装 uv 即可。

十六、常见问题排查

1. 安装成功，但命令不存在

Windows：

where.exe java
where.exe node
where.exe python
$env:Path -split ';'

WSL：

which java
which node
which python
echo "$PATH" | tr ':' '\n'

重新打开终端，确认环境变量生效。

2. IDEA 与命令行版本不一致

检查：

Project SDK；
Gradle JVM；
Maven Runner JRE；
Terminal 中的 JAVA_HOME；
Maven/Gradle Wrapper；
Run Configuration 使用的 JRE。

3. Windows 和 WSL Git 配置不一致

Windows Git 与 WSL Git 是两套程序，各自有：

1 2	`Windows: C:\Users\<user>\.gitconfig WSL: /home/<user>/.gitconfig`

分别执行：

1	`git config --list --show-origin`

4. Shell 脚本出现 `^M`

通常是 CRLF 换行导致。

转换：

1	`sed -i 's/\r$//' script.sh`

或者：

1 2	`sudo apt install -y dos2unix dos2unix script.sh`

Git 配置：

1	`git config --global core.autocrlf input`

5. WSL DNS 异常

先尝试：

1	`wsl --shutdown`

重新启动。仍异常时查看：

1 2	`cat /etc/resolv.conf ip route`

如果使用 VPN、代理或公司网络，不要直接照搬固定 DNS。应先确认 Windows 网络和 WSL 网络模式。

6. Docker 无法在 WSL 使用

检查：

1 2	`wsl --version wsl --list --verbose`

Docker Desktop 中检查：

1 2	`Use the WSL 2 based engine WSL Integration`

WSL 中检查：

1 2	`docker context ls docker version`

7. 端口被占用

Windows：

1 2	`Get-NetTCPConnection -LocalPort 8080 netstat -ano \| findstr :8080`

根据 PID 查看进程：

1	`Get-Process -Id <PID>`

WSL/Linux：

1 2	`sudo ss -lntp sudo lsof -i :8080`

8. Maven 下载慢或证书失败

先区分：

网络代理问题；
仓库镜像问题；
公司 HTTPS 证书问题；
JDK TrustStore 问题；
私服认证问题。

查看详细日志：

1	`mvn -X help:effective-settings`

不要为了绕过证书错误直接全局关闭 SSL 校验。

9. npm 下载问题

查看配置：

npm config list
npm config get registry
npm config get proxy
npm config get https-proxy

恢复官方 Registry：

1	`npm config set registry https://registry.npmjs.org/`

删除错误代理：

1 2	`npm config delete proxy npm config delete https-proxy`

10. Docker 磁盘越来越大

查看：

1	`docker system df -v`

清理前备份数据库。不要在不清楚卷用途时执行：

1	`docker system prune --volumes`

11. WSL 内存不释放

先更新 WSL：

1	`wsl --update`

配置 .wslconfig 的 autoMemoryReclaim，然后：

1	`wsl --shutdown`

紧急释放可以直接关闭 WSL，但正在运行的进程会终止。

参考资料

启示录

富贵岂由人，时会高志须酬。

能成功于千载者，必以近察远。

杂谈

#工具 #后端开发 #Linux

环境搭建相关杂谈

https://allendericdalexander.github.io/2024/05/06/env_v2/

作者

AtLuoFu

发布于

2024年5月6日

许可协议

环境搭建相关杂谈上一篇

环境搭建相关杂谈

序言

正文

一、先规划目录，再安装软件

1. 项目放在 Windows 还是 WSL

2. 不要重复安装同一套环境

二、Windows 基础环境

1. 系统与硬件检查

2. Windows Terminal

3. PowerShell 7

4. WinGet

5. Scoop 与 Chocolatey

6. Windows 环境变量

7. PATH 过长与长路径问题

三、WSL2 安装 Ubuntu、迁移、备份与卸载

1. 安装 WSL2

2. 直接安装到指定目录

3. 迁移 WSL 到 D 盘

4. 备份与恢复

5. 卸载 WSL 发行版

6. WSL 资源限制

7. 开启 systemd

8. Ubuntu 初始化

9. Ubuntu 软件源

四、AI 环境

1. Python 环境选型

2. Windows 使用 uv

3. WSL/Linux 使用 uv

4. Miniconda

5. NVIDIA 驱动

6. Driver、Toolkit、Runtime 与 cuDNN

7. Windows 原生 CUDA Toolkit

8. WSL2 使用 NVIDIA GPU

9. 安装 PyTorch

10. PyTorch GPU 验证脚本

11. 常见 AI 环境问题

nvidia-smi 正常，但 torch.cuda.is_available() 为 False

nvcc 不存在

cuDNN 手动复制后冲突

五、通用开发工具

1. Git

SSH Key

GitHub、GitLab、Gitee 多账号

2. 代码托管平台

3. 终端和远程管理

4. Web 服务器和应用服务器

六、容器环境

1. Docker Desktop

2. Docker 数据位置

3. 本地数据库 Docker Compose

4. Kubernetes 与 CRI

七、前端开发环境

1. Node.js 版本管理

2. npm、pnpm、Yarn 与 Corepack

3. nrm

4. VS Code

5. WebStorm 与 HBuilderX

6. 创建 Vite 项目验证

八、Java 后端开发环境

1. JDK 发行版选择

2. Windows 安装 JDK

3. WSL 使用 SDKMAN

4. Maven

Maven 本地仓库

Maven Wrapper

5. Gradle

6. IntelliJ IDEA

7. Spring Boot 环境验证

九、Python、Go、PHP 与 .NET 开发环境

1. Python 开发工具

2. Go

3. PHP

4. .NET

十、数据库开发环境

1. 数据库服务推荐方式

2. 数据库客户端

3. 数据库建模

十一、接口调试、抓包与网络工具

1. 接口调试

2. 抓包与代理

`nvidia-smi` 正常，但 `torch.cuda.is_available()` 为 `False`

`nvcc` 不存在

4. Shell 脚本出现 `^M`