Git on Jiangwan's Blog

解决 Windows 环境下 Git SSH Permission denied 报错

Mon, 30 Mar 2026 00:00:00 +0000

一、现象描述

在 Windows 环境下配置 GitHub SSH 密钥时，常常会遇到一个充满迷惑性的报错现象。当我们在终端直接测试 SSH 连接：

ssh -T git@github.com

终端会正常返回欢迎信息，证明密钥配置无误：

Hi your_username! You've successfully authenticated...

但紧接着执行 git clone 或 git push 命令时，却直接报错拒绝访问：

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

二、问题排查

现象表现为同一台电脑对同一份密钥的读取结果前后矛盾。为了确认 Git 在执行网络请求时到底发生了什么，我们可以开启 Git 的 SSH 调试模式。在终端临时注入环境变量，强制输出 Git 底层的 SSH 调用日志：

GIT_SSH_COMMAND="ssh -v" git clone git@github.com:your-name/your-repo.git

通过详细日志可以观察到，git clone 并没有调用系统默认的 SSH 程序，也没有去正确的 ~/.ssh 目录下寻找刚刚配置好的私钥。

三、原因分析

这个问题的核心在于：Windows 系统中同时存在两个互不相通的 SSH 程序。

  graph TD
    A[终端环境] --> B{执行指令}
    B -->|ssh -T| C[Windows 原生 OpenSSH]
    B -->|git clone| D[Git 自带内部 SSH]
    
    C -->|读取 C:\Users\用户名\.ssh| E[找到私钥]
    E --> F[连接 GitHub 成功]
    
    D -->|MSYS2 模拟环境| G[路径解析偏差 / 无法读取 ssh-agent]
    G --> H[找不到私钥]
    H --> I[Permission denied]

1. Windows 原生 OpenSSH

从 Windows 10 开始，微软内置了一套原生的 OpenSSH 工具，路径为 C:\Windows\System32\OpenSSH\ssh.exe。执行 ssh -T 时，系统默认唤醒的是这个原生程序。它能准确识别当前 Windows 用户的 ~/.ssh 目录并读取私钥，因此测试顺利通过。

2. Git for Windows 自带 SSH

安装 Git 时，为了兼容旧版 Windows，Git 官方打包了一个专属的 SSH 程序，路径通常在 C:\Program Files\Git\usr\bin\ssh.exe。执行 git clone 时，Git 会强制调用自带的内部 SSH。由于该程序运行在一个模拟的 Linux 环境 MSYS2 中，它对文件路径的解析或对 Windows 系统 ssh-agent 密钥代理服务的读取存在偏差。这导致它在连接 GitHub 时交不出密钥，从而被服务端拒绝。

四、解决方案

明确了问题是环境割裂导致的，修复逻辑就是统一底层调用。我们需要通过 Git 的全局配置，覆写它的默认行为，强制 Git 放弃内部自带的 SSH，转而调用 Windows 系统的原生 SSH 程序。

在终端执行以下配置命令：

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

执行完毕后，Git 的网络操作与系统的 ssh 命令彻底打通，底层调用的都是同一个能正确找到密钥的程序。再次执行 git clone 即可顺利拉取代码。

五、总结

在开发环境搭建中，多套工具链附带的同名依赖组件往往是引发底层冲突的根源。遇到配置生效不一致的情况，利用 GIT_SSH_COMMAND="ssh -v" 这类环境变量暴露出底层的真实调用路径，是打破信息差、快速定位问题的有效手段。

Git Commit 规范与最佳实践：为什么我们需要约定式提交

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

在个人项目的早期阶段，我们往往习惯于随意地提交代码：update、fix bug，甚至是一个单独的 .。然而，当项目周期拉长，或者开始与他人协作、参与开源社区时，这种随意的习惯会迅速带来灾难——在排查历史 Bug 或进行代码回滚时，杂乱无章的 git log 犹如大海捞针。

建立 Git Commit 规范，不仅是为了让提交历史看起来整洁，更是为了降低沟通成本、实现自动化（如自动生成 Changelog），以及方便未来的自己进行“代码考古”。

目前开源社区中最为主流的标准是约定式提交（Conventional Commits）。本文将对其核心规则与日常最佳实践进行梳理。

一、核心规则：约定式提交拆解

约定式提交要求每次提交信息必须符合固定的结构：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

在日常开发中，我们最常用的是第一行（Header）。它由三个部分组成：

1. Type（提交类型）

Type 用于明确指出这次提交的性质。严谨界定 Type 是规范的核心，以下是常用的类型及其边界：

feat: 新增功能（Feature）。
fix: 修复 Bug。
docs: 仅包含文档的修改（如 README、接口注释）。
style: 代码格式变动（不影响代码逻辑，如空格、缩进、去除多余空行等）。
refactor: 代码重构（注意边界：既不是新增功能，也不是修复 Bug 的代码变动）。
perf: 优化性能的代码修改。
test: 添加缺失的测试或更正现有测试。
chore: 构建过程、辅助工具或依赖库的变动（如更新 npm 包、修改 webpack 配置）。

2. Scope（作用域）

Scope 用于说明 commit 影响的范围，比如 auth、router、db 等。它可以帮助团队成员快速定位改动发生的模块。例如： feat(auth): 新增 JWT 登录支持。

3. Description（描述）

简短地描述改动内容。几个书写建议：

动宾结构：以动词开头，如“新增 xxx”、“修复 xxx”。
精简准确：不要超过 50 个字符，说清楚“做了什么”即可。

二、最佳实践：Commit 的颗粒度与习惯

仅仅记住格式是不够的，规范的落地还需要良好的工程习惯支撑。

1. 控制合理的提交颗粒度

一个 Commit 应该只包含一个逻辑上的改动。 这是新手最容易踩的坑。如果在开发新功能时顺手修复了一个历史 Bug，或者格式化了整个文件，请务必将它们拆分为多个独立的 Commit（例如一个 feat，一个 fix，一个 style）。

过大的、揉捏了各种变动的 Commit 会让代码审查（Code Review）变得异常困难，一旦新功能引发线上故障，想要单纯回滚那个附带的 Bug 修复几乎不可能。

2. 关联 Issue 或任务流

如果是为了解决某个特定的 Issue 或需求，应该在提交信息中（通常在 Footer 部分，或者直接在 Description 末尾）附带 Issue 编号。例如： fix(user): 修复并发注册时的锁问题 (#123)

主流的托管平台（如 GitHub、GitLab）会自动将这个 Commit 与对应的 Issue 关联并闭环。

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 补救拉取)。