开发环境 on Jiangwan's Blog

Git 基础配置与 VS Code 协同指南

Sat, 21 Mar 2026 00:00:00 +0000

在日常的开发与项目协作中，一套顺畅的 Git 工作流是不可或缺的基建，能大幅提升开发和团队协作效率。本文旨在梳理 Git 的基础环境配置，演示如何利用 VS code，将 Git 的底层空间概念通过可视化操作的方式，实现代码的拉取与推送。

一、基础环境准备

进行版本控制和代码编写，首先需要准备好 Git 和编辑器环境。

1. Git 下载与安装

Windows：前往 Git 官方网站下载安装包，常规情况下一路点击“下一步”保持默认配置即可。
macOS：推荐使用 Homebrew 安装，终端执行 brew install git。

安装完成后，在终端（Terminal 或命令提示符）输入 git --version，若能正确输出版本号，即代表安装成功。

2. VS Code 安装

前往 Visual Studio Code 官网下载对应系统的安装包。

💡 小提示：Windows 用户在安装向导中，建议勾选“将‘通过 Code 打开’操作添加到 Windows 资源管理器文件/目录上下文菜单”，这样后续在文件夹里右键就能直接用 VS Code 打开项目，非常方便。

3. 全局身份配置

Git 是分布式版本控制系统，每一次代码提交（Commit）都需要记录是谁完成的。因此，安装后的首要任务是配置全局的用户名 and 邮箱。在终端中执行以下命令（替换为你自己的信息）：

git config --global user.name "Jiangwan"
git config --global user.email "your_email@example.com"

💡 命名与邮箱建议：

公司/团队协作：建议 user.name 使用真实姓名或工号拼音，邮箱使用公司企业邮箱，方便在 GitLab 等内部系统中追溯代码责任人。

个人开发/开源社区：建议使用网名或常用昵称（如 GitHub ID），邮箱与 GitHub/Gitee 注册邮箱保持一致，以便平台正确统计你的提交贡献（绿点）。

二、鉴权：打通本地与远程仓库

要在本地电脑和云端之间传输代码，必须解决权限认证问题。主要有 HTTPS 和 SSH 两种协议。

为什么开发者更偏爱 SSH 而非 HTTPS？ 很多公司内部使用 HTTPS 也很顺畅，那是因为 Git Credential Manager 帮你缓存了账号密码或 Token。但从底层体验上，SSH 有几个核心优势：

网络与代理友好：在国内使用 GitHub 时，HTTPS 往往需要频繁配置 Git 代理（http.proxy），否则极易网络超时。而 SSH 走的是 22 端口，认证机制不同，配置代理规则也更底层且灵活。
安全性更高且无过期烦恼：HTTPS 的 Token 会有过期机制，而 SSH 采用非对称加密的“公钥-私钥”对，只要私钥不泄露，鉴权通道就一直安全有效。

1. 生成 SSH 密钥 (推荐 Ed25519)

以往的教程常教大家生成 rsa 密钥，但目前 GitHub 和技术社区更推荐使用 ed25519 算法。相比 RSA，它生成的密钥更短、生成和验证速度更快，且安全性更高。在终端中运行以下命令，连续按回车键保持默认设置（不需要设置额外密码）：

ssh-keygen -t ed25519 -C "your_email@example.com"

(注：如果你的旧系统不支持 ed25519，再退回使用 ssh-keygen -t rsa -b 4096 -C "..." 即可)

2. 配置公钥至托管平台

密钥生成后，包含公钥（.pub 结尾）和私钥。我们需要将公钥提供给托管平台。查看并复制公钥内容：

cat ~/.ssh/id_ed25519.pub

将终端打印出的字符复制。登录 GitHub，进入 Settings -> SSH and GPG keys -> New SSH key，将其粘贴并保存。

3. 连接测试

在终端输入以下命令验证是否配置成功：

ssh -T git@github.com

如果看到类似 Hi [Username]! You've successfully authenticated... 的提示，说明鉴权通道已打通。

三、参与协作：加入 GitHub 组织 (Organization)

在实际的兴趣小组开发或开源协作中，我们经常需要先加入一个 GitHub 组织，才能获取内部代码仓库的协同权限。

1. 接受组织邀请

组织管理员会通过你的 GitHub 用户名或注册邮箱发送邀请。留意你的邮箱邮件，或者直接登录 GitHub，点击右上角的通知小铃铛（Notifications），找到邀请信息并点击 “Join” 即可。加入后，你可以在个人主页左侧的 Organizations 列表中看到该组织。

2. 踩坑提示：拉取与推送权限

注意：加入组织后，你通常可以直接 Clone 组织内的代码。但如果在后续 Push 代码时遇到 Permission denied 或 403 Forbidden 错误，这通常是因为管理员尚未给你分配目标仓库的 Write（写入）权限。 解决办法：直接联系组织的管理员，请他们将你所在的 Team 或个人账号的仓库权限从 Read 提升至 Write 即可。

四、 VS Code 协同实战：核心流转

加入组织并搞定权限后，我们就可以正式开始写代码了。在进行 Git 操作前，我们需要先理清 Git 的四个核心空间概念。

1. 核心概念前置与空间映射

以下是 Git 底层流转概念与 VS Code 可视化操作的对应关系：

  flowchart LR
    subgraph LocalEnv [本地电脑环境]
        direction LR
        Workspace[工作区<br>Working Directory]
        Index[暂存区<br>Staging Area]
        Local[本地仓库<br>Local Repository]
    end
    Remote[远程仓库<br>Remote Repository]

    Workspace -- "git add<br>(点击 + 号)" --> Index
    Index -- "git commit<br>(点击 提交)" --> Local
    Local -- "git push<br>(点击 同步更改)" --> Remote
    Remote -. "git pull<br>(自动/手动 拉取)" .-> Workspace

工作区 (Working Directory)：你在编辑器里直接看到和修改的代码文件。
暂存区 (Staging Area)：一个缓冲地带，用于挑选并确定下一次要提交哪些修改（相当于“购物车”）。
本地仓库 (Local Repository)：代码在本地的完整历史版本记录（相当于“本地结账”）。
远程仓库 (Remote Repository)：托管在云端的代码库（相当于“云端备份”）。

2. 完整工作流演示

无论你偏好可视化点击还是敲击命令行，底层流转逻辑是一致的。以下提供两种方式供你参考：

Step 1: 拉取项目 (Clone)

VS Code 方式：Ctrl+Shift+P 唤出命令面板，输入 Git: Clone，粘贴组织仓库的 SSH 地址。
Git 命令：终端执行 git clone <你的SSH仓库地址>。

Step 2: 编写代码 (Modify)

VS Code 方式：在工作区正常修改。VS Code 侧边栏“源代码管理”会提示文件被更改（M 或 U）。
Git 命令：随时可通过 git status 命令查看当前有哪些文件被修改或未被追踪。

Step 3: 暂存更改 (Stage)

VS Code 方式：点击文件右侧的 + 号。这就是把文件从“工作区”推入“暂存区”。
Git 命令：终端执行 git add .（暂存当前目录下所有更改），或指定单个文件 git add <文件名>。

Step 4: 提交版本 (Commit)

VS Code 方式：在面板输入框填写提交信息（如 feat: 新增登录接口），点击 “提交”。代码正式存入本地仓库。
Git 命令：终端执行 git commit -m "feat: 新增登录接口"。

Step 5: 推送云端 (Push)

VS Code 方式：点击 “同步更改 (Sync Changes)”，将本地仓库的新版本同步到远程仓库。 (注：VS Code 的同步按钮实际上包含了 Pull 和 Push 两个动作)
Git 命令：终端执行 git push（若需先合并远程最新代码，可先执行 git pull）。

五、进阶：分支管理与子仓库

随着项目复杂度提升，你必然会用到分支与子仓库，这两者在团队协作中极为重要。

1. 分支的新建与合并 (Branch & Merge)

为什么需要分支？ 为了不污染主线代码（main / master），开发新功能或修复 Bug 时，我们通常会拉取一个独立的分支，开发测试完毕后再合并回去。

新建与切换：在 VS Code 左下角点击当前分支名（如 main），在弹出的菜单中选择 “创建新分支 (Create new branch)”，输入新分支名（如 feat/user-login）即可自动切换。
合并分支：假设你在新分支开发完毕并提交了。先在左下角切换回 main 分支，然后 Ctrl+Shift+P 唤出面板，输入 Git: Merge Branch，选择刚才的 feat/user-login，即可将新代码合并到主线上。

2. Git 子仓库 (Submodule)

什么是子仓库？ 在大型项目或微服务架构中，你可能需要在一个主 Git 仓库里嵌套另一个 Git 仓库（比如引用一个通用的 UI 组件库，或者把公共配置抽离出来）。这就是 Submodule。

添加子仓库：在终端执行：

git submodule add <子仓库的git地址> <本地存放目录>

踩坑提示：当别人 Clone 含有子仓库的主项目时，默认情况下子仓库是空文件夹！必须使用递归拉取命令：

git clone --recursive <主仓库地址>

(如果已经 clone 完了，可以使用 git submodule update --init --recursive 补救拉取)。

Node/npm/pnpm 安装指南

Wed, 18 Mar 2026 00:00:00 +0000

一、引言

在动手安装之前，我们先理清一个概念：Node.js 是一个 JavaScript 运行环境。当你安装 Node.js 时，它会“买一赠一”地在你的系统里捆绑安装官方的包管理器，npm (Node Package Manager)。

既然官方自带了 npm，为什么大家还要折腾？答案很简单：天下苦 node_modules 久矣。

1. npm 的痛点：曾经的“依赖黑洞”

早期的 npm 有几个让开发者头疼的缺陷：

极其占空间：每个项目都会在根目录下生成一个独立的 node_modules 文件夹。如果你有 10 个项目都用到了同一个库（比如 React），这个库就会在你的硬盘里被重复下载、完整保存 10 次。
速度慢：串行安装机制导致下载速度令人抓狂。

2. pnpm 的破局：硬盘空间魔法

pnpm（Performant npm）是目前开源社区最推荐的包管理器之一，它直接解决了上述痛点。

它巧妙地使用了计算机文件系统中的 硬链接（Hard link） 技术。无论你在电脑上创建了多少个项目，只要它们用到了同一个版本的某个包，pnpm 只会在系统全局的 Store 中保存一份实体文件，然后通过硬链接将它们映射到各个项目的 node_modules 中。

结论：极速的安装时间 + 极大地节省硬盘空间 = 无脑选 pnpm。

二、实战演练

如果你只是单纯地为了跑脚手架、装依赖，直接去官网下载安装包绝对是最省事的选择。

步骤一：官网直装 Node.js

打开 Node.js 官方网站。
强烈建议下载 LTS（长期维护版），不要去碰 Current（最新尝鲜版），能避免很多莫名其妙的兼容性报错。
下载对应的 .msi (Windows) 或 .pkg (macOS) 文件，双击运行，一路点击 Next 完成安装。

安装完成后，打开终端（CMD/PowerShell/Terminal），验证是否成功：

# 验证 Node.js
node -v

# 验证赠送的 npm
npm -v

步骤二：拯救 C 盘（修改 npm 全局路径）

这是无数 Windows 开发者痛彻心扉的踩坑点。 Node 本身装在 C 盘没关系，但 npm 默认会把以后所有全局安装的包和缓存文件都塞进 C 盘的 AppData\Roaming 目录下。时间一长，C 盘直接标红。

我们需要把这部分转移到 D 盘（或其他非系统盘）：

在 D 盘的 Node.js 安装目录下（或者你自定义的一个目录，比如 D:\nodejs），新建两个文件夹：node_global 和 node_cache。
打开终端，执行以下命令重定向路径：

# 设置全局模块的安装路径
npm config set prefix "D:\nodejs\node_global"

# 设置缓存路径
npm config set cache "D:\nodejs\node_cache"

致命踩坑点：配置环境变量。因为我们修改了全局安装路径，系统现在找不到你以后全局安装的命令了。你必须告诉 Windows 去哪里找：

右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量。
在“系统变量”中找到 Path，双击编辑。
新建一条，填入你刚才创建的全局路径：D:\nodejs\node_global。
一路点击“确定”保存，然后必须重启你的终端。

步骤三：配置镜像源与激活 pnpm

网络问题是国内开发者的共同阻碍，我们需要把 npm 的下载源切换到国内镜像：

# 设置淘宝镜像源
npm config set registry https://registry.npmmirror.com/

最后，利用刚刚配置好的 npm，全局安装并激活 pnpm：

# 全局安装 pnpm（它现在会被安装到 D:\nodejs\node_global 里）
npm install -g pnpm

# 为 pnpm 同样配置国内镜像源
pnpm config set registry https://registry.npmmirror.com/

# 验证安装
pnpm -v

至此，你的电脑不仅拥有了一个干净、极速、省空间的 pnpm 环境，还成功保卫了你宝贵的 C 盘容量。以后遇到任何项目的 npm install 指令，都可以愉快地替换成 pnpm install 了。