Vue 3 + Vite 引入 iclient-ol，矢量瓦片加载实战指南
2026/9/15 1:07:12
Windows 上配 Git，说实话真不难，但我见过太多人在这一步栽跟头：下载装了一半不知道选项怎么选，装完 git 命令敲不出来，配好了仓库一 push 又提示 Permission denied，最后只能对着报错发呆。这篇教程把我这些年反复操作过的完整流程一次性写清楚，覆盖 Git 下载、安装、环境配置、SSH 密钥生成与绑定，每一步都给出明确选项和背后原因。多数内容在 2026 年当下的 Windows 11/10 上依然通用，适合刚入门的新手，也适合那些装过但一直没把 SSH 免密搞定的老哥们。整篇我尽量说人话，不堆术语，重点讲清楚每个选项到底在干什么，让你配完知道自己改了哪些东西，以后出问题也知道往哪查。
1. Windows 下 Git 的获取与安装：选项逐个过关
1.1 为什么 Windows 上推荐 Git for Windows
很多人第一次接触 Git 是在 Linux 服务器上，觉得就是一条git clone、git push的事，到了 Windows 反而懵了，因为系统本身没有带 Git 命令。Windows 上主流方案是安装 Git for Windows，也就是从 Git 官网 git-scm.com 下载的 Windows 安装包。它自带三样东西：Git 命令行工具、Git Bash 终端模拟器、Git GUI 图形界面。
这里我得特别强调 Git Bash 的价值。Git 本来是在 Unix 环境下成长起来的，很多习惯和命令都带着 Linux 的味道，而 Git Bash 在 Windows 上模拟了一套类 Unix 环境，让你能用ls、grep、ssh这些命令，体验和 Linux 终端非常接近。对于经常要跟服务器打交道的开发者来说，Git Bash 比 CMD 或 PowerShell 顺手得多。下载时认准官方渠道，在选择 64 位还是 32 位时，现在绝大多数机器直接选 64 位即可。
1.2 安装向导里的关键选项（别无脑下一步）
Git 安装过程其实没有坑到哪去，但很多人图省事一路 Next，装完发现右键菜单没有 Git Bash，或者打开 CMD 输入git --version提示“不是内部或外部命令”，问题都出在安装选项上。我把每个容易纠结的界面拆开讲。
第一个是 Select Components 界面，里面有一堆勾选项。建议把 Additional icons 里的 On the Desktop 勾上，虽然没啥用，但桌面多个图标找起来方便。Windows Explorer integration 里的 Git Bash Here 和 Git GUI Here 建议都勾上，这样在文件夹空白处右键就能直接打开终端，实用性极高。默认的 Git LFS、Associate .git configuration files 也保留勾选。
第二个是 Choosing the default editor used by Git，这里默认是 Vim。Vim 对新手实在不友好，一个不小心就卡在提交信息编辑界面不知道怎么退出。我建议选 Use Visual Studio Code，前提是你电脑装了 VS Code。如果没装，选 Nano 或者 Notepad 也凑合，总比 Vim 舒服。
第三个是 Adjusting your PATH environment，这是最重要的一个选项。默认选 Git from the command line and also from 3rd-party software，意思是不光 Git Bash 能用 Git，CMD、PowerShell、VS Code 终端也都能识别git命令。如果你想以后在任意终端里敲 git，就必须选这个。
1.3 换行符、终端模拟器和其他细节
换行符设置是 Windows 用户最该理解的一个选项。Windows 系统里文本文件换行是 CRLF（回车+换行），Linux/macOS 里是 LF（只有换行）。同一个文件在两个系统之间传来传去，如果不做转换，会出现一堆奇怪的差异。Git 的解决思路是：检出代码时按 Windows 规则转成 CRLF，提交代码时统一转成 LF 存进仓库，保证仓库内部永远是 LF，这样团队协作不会因为换行符打架。所以默认选项 Checkout Windows-style, commit Unix-style line endings 直接用，不用改。
再往下是 Choosing the terminal emulator。默认 Use MinTTY，我建议保持默认。MinTTY 支持颜色、快捷键、复制粘贴更顺手，表现比 Windows 自带控制台好很多。不过如果你在 MinTTY 里遇到中文乱码或者复制粘贴不习惯，重新装一次改成 Windows Console 也完全可以，这是体验问题，不影响 Git 本身。
整体安装时间也就是几分钟，装完先打开 PowerShell 或 CMD，输入git --version看看能否正常输出，再打开开始菜单确认 Git Bash 是否出现。到这里，Git 本身就算装完了，接下来才是真正决定你用得舒不舒服的环境配置环节。
2. 环境配置：让 Git 真正开箱好用
2.1 核心身份配置：user.name 和 user.email
Git 每次提交都会记录作者信息，这个信息是写在提交记录里的，不配好会导致提交不了，或者提交到公共仓库后显示成一个奇怪的名字。配置方法很简单，在终端里执行两条命令：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"--global表示全局生效，对当前 Windows 用户的所有仓库都有效。如果你某个仓库要用不同身份，可以在那个仓库目录下不加--global重新配置，这种是 local 级别，只对当前仓库生效。检查是否配置成功用这个：
git config --global --list这里有个小细节容易被忽略：如果你用 GitHub，且开启了邮箱隐私保护，最好在 GitHub 设置里复制那串xxxxx@users.noreply.github.com邮箱来配置，避免把真实邮箱暴露在公开提交记录里。邮箱可以乱填吗？可以，但提交记录里会留下一个无效邮件，以后别人找你对账都联系不上你，不建议这么干。
2.2 换行符、默认分支和常用别名
身份配置完，我建议顺手把下面几个配置也改了，都是实际使用中反复遇到的痛点。
默认分支名。Git 老版本默认分支叫 master，现在主流平台都推荐 main。用下面命令把默认分支设为 main，以后git init出来的仓库直接就是 main：
git config --global init.defaultBranch main换行符策略单独再强调一次，直接用下面这条命令配置，效果和安装时选默认项一致：
git config --global core.autocrlf truetrue的意思是检出时转 CRLF、提交时转 LF。如果你经常写 shell 脚本，.sh文件在某些场景下会因为 CRLF 报错，这时候可以额外加一个.gitattributes文件来指定特定文件不转换，后面讲忽略文件时一起说。
提交信息编辑器，如果安装时选了 VS Code，Git 默认会用 VS Code 打开提交信息编辑界面。如果没选，建议再手动指定一次，避免某些环境回落成 Vim：
git config --global core.editor "code --wait"还有几个常用别名是我每次重装都会配的，能省下大量打字时间：
git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.cm commit git config --global alias.lg "log --oneline --graph --all --decorate"配完之后，git lg就能看到一个带分支和提交图的信息列表，比默认 log 好看得多。
2.3 用 .gitignore 管好“不该提交”的文件
很多人提交代码时把node_modules、bin、obj、IDE 配置文件一起 push 上去，造成仓库又大又乱，别人 clone 下来还会因为路径问题出各种幺蛾子。正确做法是在仓库根目录添加.gitignore文件，把不需要版本控制的文件排除掉。
Windows 开发环境要注意几个点：Visual Studio 的项目要忽略.vs文件夹、*.user文件、Debug/Release输出目录；VS Code 要忽略.vscode里的个人设置，但团队共享的settings.json如果约定要提交，就单独处理；Node 项目必须忽略node_modules；Python 项目忽略venv、__pycache__。
一个比较通用的 Windows 开发.gitignore模板大致这样：
# Windows Thumbs.db Desktop.ini # IDE / 编辑器 .vs/ .idea/ .vscode/ *.user *.suo # 构建输出 bin/ obj/ dist/ build/ # 依赖目录 node_modules/ venv/ __pycache__/ # 日志和临时文件 *.log *.tmp另外还有一个容易被坑到的东西：如果你在仓库里定义了.gitattributes，里面可以强制某些文件使用 LF 或 CRLF，例如设定*.sh text eol=lf，这样 shell 脚本不管在哪台机器上检出都是 LF，避免 Windows 下脚本执行报错。这个文件本身也应该提交到仓库里，团队共用。
2.4 保存凭证：告别每次都要输入密码
Git 连接远程仓库时，如果使用 HTTPS 方式，默认每次 push 都要验证账号和密码。Windows 上 Git 自带的 Git Credential Manager 可以帮你管理凭证，首次输入后，凭证会安全存储在 Windows 凭据管理器里，后续自动使用。
检查是否启用：
git config --global credential.helper manager配置好之后，第一次通过 HTTPS 克隆或推送时，会弹出一个登录窗口，完成一次认证即可。很多人问“为什么我每次 push 都提示输入账号密码”，基本都是因为 clone 时用的 SSH 地址，或者 Credential Manager 没正确配置。关于 SSH 方式怎么做到彻底免密，下一章详细说。
3. SSH 密钥生成与配置：从零到免密推送
3.1 为什么推荐 SSH 而不是 HTTPS
连接远程仓库有 HTTPS 和 SSH 两种方式。HTTPS 方式配置简单，输入账号密码即可，但即使有凭证管理器，有些场景还是会反复要你输密码，比如多账号切换、公司自建 GitLab 做了二次验证。SSH 方式的核心优势是免密和可信：你生成一对密钥，公钥放到 Git 服务商，私钥留在本地，推送时 Git 用私钥签名，服务商用公钥验证，过程不传输密码，也不怕密码泄露。
可以用门锁类比：公钥是锁，私钥是钥匙。你把锁挂在服务器上，钥匙留在自己兜里，别人没有钥匙就进不去。服务器只认钥匙是否匹配锁，不需要知道你的密码。
要特别提醒：私钥文件.ssh/id_ed25519就是你的“钥匙”，绝对不能发给任何人，也不能上传到公开仓库。我之前见过有人把id_rsa提交到 GitHub 仓库里，结果被爬虫扫到，整个账号的服务器差点被登录，处理起来非常麻烦。
3.2 生成 SSH 密钥：Ed25519 还是 RSA
Windows 10 1809 及以上版本自带了 OpenSSH 客户端，所以不用额外装任何工具，直接用终端就能生成密钥。打开 PowerShell 或 Git Bash，执行：
ssh-keygen -t ed25519 -C "你的邮箱或备注"-t指定加密算法，ed25519是目前推荐的安全算法，密钥短、速度快、安全性高。-C是备注信息，一般是邮箱或者你的用户名，方便以后在服务器上区分密钥。
执行后会问你保存位置，默认是C:\Users\你的用户名\.ssh\id_ed25519，直接回车即可。随后会提示你设置 passphrase（口令），这是给私钥再加一层密码保护。建议设置，即使私钥文件被拷走，对方没有口令也用不了。担心每次都要输口令的，后面可以用 ssh-agent 记住，不用每次手动输入。
如果某些老旧的 Git 服务商不支持 Ed25519，只能用 RSA，那生成时用这条命令：
ssh-keygen -t rsa -b 4096 -C "你的邮箱或备注"生成完成后，.ssh目录下会有两个文件：id_ed25519是私钥，id_ed25519.pub是公钥。查看公钥内容用：
cat ~/.ssh/id_ed25519.pubWindows 下如果cat不生效，用type %USERPROFILE%\.ssh\id_ed25519.pub也行。后面要复制这串内容到 Git 服务商。
3.3 启动 ssh-agent 管理私钥
设置了 passphrase 之后，每次 SSH 连接理论上都要输入口令，体验有点烦。解决办法是把私钥交给 ssh-agent 托管。ssh-agent 是 OpenSSH 自带的一个后台服务，负责保管私钥，并在需要时替你签名。
先确认 ssh-agent 服务有没有运行，Windows 下可以用管理员身份打开 PowerShell：
Get-Service ssh-agent如果状态不是 Running，执行：
Set-Service -Name ssh-agent -StartupType Automatic Start-Service ssh-agent这里Automatic表示开机自动启动。配置好后，在 PowerShell 里执行：
ssh-add $env:USERPROFILE\.ssh\id_ed25519输入一次 passphrase，之后这台机器上再使用 SSH 就不需要重复输口令了。在 Git Bash 里则习惯用：
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519要注意的是，Git Bash 和 PowerShell 里的 ssh-agent 是相对独立的会话，重启终端后，PowerShell 托管的密钥通常还在，Git Bash 里的代理会话可能失效，需要重新ssh-add。这个问题不影响功能，只是偶尔忘记会报 Permission denied，需要有个心理预期。
3.4 把公钥添加到 GitHub/GitLab 并测试连接
复制好公钥内容后，登录 GitHub，进入 Settings，找到 SSH and GPG keys，点 New SSH key，标题随便写，比如“My Windows PC”，把公钥粘贴到 Key 文本框里，保存即可。GitLab 的路径通常是在 Preferences 或 User Settings 里找 SSH Keys，操作逻辑一样。
添加完成后，测试连通性：
ssh -T git@github.com注意用户名是git，不是你的 GitHub 账号。首次连接会提示确认服务器的指纹信息，询问是否继续连接，输入yes回车即可。如果一切正常，GitHub 会返回类似这样的内容：
Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.看到这句话就说明 SSH 密钥配置成功了。GitLab 测试命令是ssh -T git@gitlab.com，返回 Welcome to GitLab 字样同样代表成功。
这里有个细节：GitHub 的服务器指纹可以提前在官方文档查到，但更简单的做法是把返回的指纹和官方公布的比对，确认没被劫持。虽然实际中被中间人攻击的概率极低，但这个习惯能帮你避开很多安全坑。
3.5 多账号与 ~/.ssh/config 配置
实际工作中，很多人一台电脑要同时使用 GitHub 和公司 GitLab，甚至还有几个客户的代码仓库。每个服务商都配同一个公钥，服务商之间会互相认，但如果你希望不同平台用不同私钥，或者同一台电脑上不同 Git 账号推不同的仓库，就需要用到~/.ssh/config配置文件。
假设你有两个私钥：~/.ssh/id_ed25519_github和~/.ssh/id_ed25519_gitlab，先分别生成并添加公钥到对应平台，然后编辑~/.ssh/config（没有就新建）：
Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/id_ed25519_gitlab IdentitiesOnly yesIdentitiesOnly yes的作用是告诉 SSH 只用指定的私钥，不要把所有私钥挨个试一遍，这样能避免多账号时因为默认私钥被拒绝而连不上。
还有一种情况是公司 GitLab 用了非 22 端口，可以在 Host 下面写Port 2222。改完后用ssh -T git@github.com测试一遍，确认 config 生效。以后git clone git@github.com:xxx取仓库时，Git 会自动加载对应私钥，完全无感。
4. 日常 Git 操作和 VSCode 远程连接实践
4.1 最常用的几个 Git 命令组合
SSH 配好之后，日常开发的高频操作其实就那么几个。新项目拉代码：
git clone git@github.com:用户名/仓库名.git改完代码提交并推送，标准流程：
git status git add . git commit -m "提交说明" git pull --rebase git push这里我要重点说git pull --rebase。很多人习惯直接git pull，如果本地有提交且远程也有新提交，Git 会生成一个 merge 提交，提交历史变得很乱。用--rebase会把本地提交“回放”到远程最新提交之上，历史是直线，干净得多。第一次用不习惯很正常，但用多了回不去。
查看这次改了什么，用git diff；查看历史记录，用我前面配好的git lg。这套组合已经覆盖了日常开发 80% 的场景，不需要背更多命令。真正需要深入学习的是解决冲突。冲突提示CONFLICT (content)时，打开冲突文件，搜索<<<<<<<、=======、>>>>>>>标记，手动选择保留哪部分，然后git add和git commit即可。
4.2 VSCode 里的源码管理和 Git 面板
装了 VS Code 的人，不用天天开终端也能完成大部分 Git 操作。左侧栏的源代码管理图标，会列出所有修改文件；文件旁边的 M、U、A 分别代表修改、未跟踪、已添加。在输入框里写提交信息，点提交，再点同步，就是一次完整的提交流程。
VS Code 内置的 Git 继承你 Windows 里的全局配置，所以之前配好的 user.name 和 SSH 密钥都直接生效。唯一要注意的是，如果在 VS Code 里点提交后没反应，多半是默认编辑器被设置成了 VS Code 但无法弹出提交信息窗口，可以检查全局配置里core.editor是否设置正确。
还有一个高频问题：多人协作时，远程仓库更新了，本地也有修改，这时 VS Code 会提示“同步更改”失败。不要慌，打开终端跑一次git pull --rebase，解决冲突后再同步即可。
4.3 VSCode 连接 SSH 远程服务器
配置 SSH 还有一个大用途：让 VS Code 直接连接远程服务器开发。这个场景对后端开发和部署特别实用，本地只写界面和提交，真正跑代码、改文件都在服务器上完成。
先确保~/.ssh/config里配好了服务器条目，例如：
Host my-server HostName 192.168.1.100 User root IdentityFile ~/.ssh/id_ed25519然后在 VS Code 里安装 Remote - SSH 插件，安装后左侧会出现远程资源管理器，点加号选择 Connect to Host，输入或选择配置好的主机名。连接成功后，底部状态栏会显示当前连接的服务器地址，左侧打开的就是远端目录，可以像本地一样编辑、运行终端命令。
这里有个常见的坑：有些扩展装好后提示“此扩展在此工作区中被禁用，因为其被定义为在远程扩展主机中运行”，这是因为某些扩展只支持远程端、不支持本地端，或者反过来。解决办法是在扩展页面里把扩展安装到 SSH 远程主机那一侧，或者换用标注为 Remote 的版本。本质是扩展的运行位置不对，不用卸载，直接切换安装目标就能解决。
5. 常见报错与排查思路实录
5.1 高频问题速查表
我整理了一张表格，把 Windows 上 Git + SSH 配置时最容易遇到的报错和解决思路写在下面，建议收藏。
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 输入 git 提示“不是内部或外部命令” | 安装时 PATH 选错了 | 重装并选择“Git from the command line”；或手动把 Git 的 cmd 目录加入系统 PATH |
| Permission denied (publickey) | 公钥未添加、私钥未加载或 ssh-agent 没启动 | 检查ssh -T git@github.com；重新ssh-add私钥；确认.ssh/config指向的 IdentityFile 正确 |
| connection timed out | 网络不通、SSH 端口被防火墙拦截 | 先ping或telnet测试；可尝试将 GitHub 的 SSH 服务改为 443 端口连接 |
| warning: LF will be replaced by CRLF | Windows 换行符转换提示，属于正常提醒 | 不需要解决；如果脚本文件报错，用.gitattributes固定特定文件为 LF |
| fatal: refusing to merge unrelated histories | 本地和远程仓库没有共同提交记录 | 第一次合并时用git pull --rebase --allow-unrelated-histories |
| Host key verification failed | 远程服务器指纹不在 known_hosts 或指纹变化 | 确认指纹可信后删除旧指纹记录，ssh-keygen -R 服务器地址，重新连接 |
| 每次 push 都要输入账号密码 | 用了 HTTPS 且凭证管理器未生效 | 配置credential.helper manager；或换成 SSH 方式 clone |
5.2 SSH 连接被防火墙拦时的替代端口方案
默认 SSH 走 22 端口，但在某些网络环境里，22 端口会被防火墙拦截，导致ssh -T git@github.com一直卡住或超时。GitHub 官方提供了一个替代方案：用 443 端口连接。
修改~/.ssh/config，把 GitHub 的配置改成这样：
Host github.com HostName ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519改完后测试ssh -T git@github.com，如果返回成功的提示，说明 443 端口可以正常工作。这个方法也可以解决很多公司网络只开放 80/443 端口导致 SSH 连不上的问题。要注意的是，这里的 HostName 变成了ssh.github.com，不要漏写。
5.3 换行符引起的诡异问题
Windows 里最隐蔽的坑就是换行符。代码文件在本地看着好好的，提交到服务器上执行 bash 脚本报\r: command not found，或者在 Git 里看到整个文件被标记为修改，就是因为 CRLF 和 LF 混用了。
排查思路：先看仓库根目录有没有.gitattributes，没有的话建议加一份，并至少包含下面两行：
* text=auto *.sh text eol=lf* text=auto让 Git 按内容自动检测文本文件；*.sh text eol=lf单独把 shell 脚本固定为 LF。加完后重新提交一次，如果文件仍显示为整体改动，执行git add --renormalize .把所有文件按新规则重新规范化一次，再提交即可。
5.4 配置文件写错导致的连接异常
SSH 连接连不上，优先怀疑~/.ssh/config格式问题。OpenSSH 的配置对缩进和大小写不敏感，但属性名不能写错，比如IdentityFile不要写小写，HostName不要漏大写。检查配置是否被读取，可以用：
ssh -G github.com这个命令会输出实际生效的配置项，包括 HostName、Port、IdentityFile 等。如果输出里的 HostName 不是预期值，说明 config 里可能有多个 Host 块匹配到了，或者配置顺序不对。OpenSSH 的匹配规则是第一个匹配到的 Host 生效，所以把更具体的配置写在前面，通用配置写在后面。
另外，~/.ssh目录和私钥文件的权限在 Windows 里一般不强制检查，但如果你的 OpenSSH 版本较新且开启了严格模式，权限过宽也可能被拒绝。右键私钥文件，在属性-安全里确认当前用户有读取权限即可。
最后分享一点我自己的使用体会
这套流程我前前后后至少帮别人重装过几十次，最大的体会是：安装时的几个选择比安装本身更值得花时间，尤其是 PATH 和换行符策略，一开始配错了后面到处都是小毛病。SSH 密钥部分，很多人第一次配完觉得麻烦，但配好之后那个免密推送的体验是真的回不去，特别是配合 ssh-agent 连 passphrase 都不用输，每天几百次提交都不觉得卡手。还有一个小技巧：如果你换了新电脑，别重新生成密钥，直接把旧的.ssh目录整个拷过去，然后确认 ssh-agent 启动了就行，省得又在各平台重新添加公钥。如果配完还是有问题，优先执行ssh -T测试，再逐条检查 config 文件，八成能在五分钟内定位到问题。