这几年我前后换了两家公司、带过几批新人每次给新环境配开发机第一步几乎都是同一件事把代码托管平台打通。早些年大家默认往 GitHub 上扔后来在国内做项目越来越多的团队第一选择变成了 Gitee。原因很简单——拉取速度快、私有仓库免费、中文文档友好社区里的项目也越来越有参考价值。这篇内容不是官方教程的复读而是我实际用 Gitee 做项目、带团队、搭个人站点踩过的一系列经验汇总覆盖从配置 SSH 密钥、拉取项目到 IDEA、上传代码、选开源许可证、部署 Pages 和传大文件这些日常操作希望能让刚接触 Gitee 的朋友少走弯路也让已经在用的同学看看有没有遗漏的顺手技巧。1. 先聊为什么本土化平台解决的真实痛点1.1 网络与体验的平衡点可能有人会觉得不就是个代码托管平台吗GitHub 全球都在用为什么要额外折腾一个 Gitee我在实际使用中最直观的感受是速度和稳定性。GitHub 在国内的访问体验时好时坏尤其是 push 大项目、拉取依赖较多的仓库时经常出现半天没反应或者直接 RPC failed。团队协作的时候这种等待特别磨人新成员 clone 一个中等规模的仓库可能要等很久。Gitee 的服务器在国内拉取和推送的响应速度确实快很多。我测试过同一个仓库在相同网络环境下Gitee 的 clone 速度经常是 GitHub 的好几倍这对于日常频繁的代码同步来说体验差距是实打实的。当然GitHub 上开源项目更多、社区氛围更国际化所以我自己是两边一起用国内业务相关的代码放 Gitee需要对外开源或者参与国际社区的项目继续放 GitHub。这不冲突关键看你项目的协作对象和网络环境。1.2 私有仓库免费带来的协作方式变化Gitee 对我这种小团队负责人最友好的一点是私有仓库免费且数量没有太多限制。GitHub 的免费私有仓库虽然现在也普及了但团队规模超过一定人数就要收费而且一些高级协作功能需要订阅。Gitee 在这块放得比较开小团队直接建私有仓库把代码、Issue、文档全放进去零成本就能获得一套完整的协作闭环。创新范式这个词听起来挺大落到日常开发里其实就是一件事你愿不愿意把一个想法从第一天就开始托管、迭代、留痕。因为私有仓库免费很多小项目、临时脚本、学习笔记你都愿意往里放而不是憋到成熟了才见光。东西放上去了才有可能被不断打磨。我觉得这才是重塑开发者创新范式最接地气的理解——降低托管门槛让更多人把写代码升级成做项目。1.3 中文生态的隐形加成还有一点很容易被忽略Gitee 的中文支持是原生级的。不只是界面是中文而是从帮助文档、Issue 交流、PR 讨论到平台内部的官方活动整个生态都是中文的。这对国内开发者的意义很大。我的团队里有实习生以前用 GitHub 时连 issue 模板都要查英文怎么写现在在 Gitee 上他们可以更专注于技术本身。遇到问题搜官方帮助、看社区经验贴中文资料也丰富得多。这个隐形加成在排障时的价值极高——省掉了先理解英文、再翻译成技术理解的过程。2. 从 Gitee 拉取项目到 IDEA第一件要做的事2.1 先把 SSH 密钥配好别急着敲命令很多教程上来就让你复制 HTTPS 地址去 clone结果每次 push 都要输用户名密码特别烦。我的建议是不管你是用 IDEA、VS Code 还是纯命令行第一步都先配好 SSH 密钥一劳永逸。配置步骤其实很简单在终端执行ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车即可。如果之前生成过密钥可以指定新文件名避免覆盖ssh-keygen -t ed25519 -C 你的邮箱example.com -f ~/.ssh/gitee_ed25519生成后查看公钥内容cat ~/.ssh/gitee_ed25519.pub复制这段内容打开 Gitee 的设置 - SSH 公钥粘贴进去标题可以写我的笔记本之类方便识别的名字然后保存。最后验证一下是否成功ssh -T gitgitee.com第一次连接会提示确认指纹输入yes看到类似Hi XXX! Youve successfully authenticated, but GITEE.COM does not provide shell access.的信息就说明成功了。我之前一直用老教程里的 RSA 算法后来发现 ed25519 更安全、生成的密钥更短、连接速度也更快。如果你用的是比较老的系统可能需要确认 OpenSSH 版本支持 ed25519现在主流系统和 Git for Windows 基本都支持可以放心用。2.2 把 Gitee 仓库拉进 IDEASSH 配置好之后拉取项目到 IDEA 就很顺了。在 Gitee 的仓库页面点克隆/下载选择 SSH 格式的地址注意是gitgitee.com:用户名/仓库名.git这种格式不是https://开头的那种。然后在 IDEA 里操作点击File-New-Project from Version Control...在弹出的对话框里粘贴刚才复制的 SSH 地址选择要存放项目的本地目录点击Clone等 IDEA 拉完代码后会自动打开打开后 IDEA 一般会弹出一个Trust Project的确认窗口这是让你确认是否信任该项目的构建脚本建议勾选信任否则后续 Maven 或 Gradle 的自动构建功能可能受限。这里有个小细节如果 IDEA 提示找不到 Git你需要到Settings-Version Control-Git里指定 Git 可执行文件的路径。Windows 上通常是C:\Program Files\Git\bin\git.exemacOS 上通常位于/usr/bin/git。IDEA 内置了一些 Git 操作但它底层仍然依赖你系统里安装的 Git。2.3 VS Code 搭配 Gitee 的轻量玩法如果你更喜欢 VS Code流程同样不复杂。VS Code 自带源码管理面板只要你把 SSH 密钥配置好在命令面板里执行Git: Clone粘贴 Gitee 的 SSH 地址就可以拉取。日常提交代码步骤如下修改文件后点击左侧源代码管理图标在更改区域点击文件旁边的号暂存在输入框里填写提交信息点击上方提交按钮提交后点击同步更改按钮或执行git push我习惯给 VS Code 装一个 GitLens 插件查看每行代码的提交历史、作者、提交时间都非常直观定位这行代码是谁在什么时候改的、为什么改这种问题效率极高。这个组合对于个人项目和轻量团队协作都够用了不需要单独打开命令行。注意VS Code 需要先在本机安装 Git否则源代码管理面板会提示找不到 Git。装完 Git 后重启 VS Code 即可。3. 上传代码到 Gitee 仓库从零到一的完整流程3.1 创建仓库时的三个决策点在 Gitee 上新建仓库时有几个选择会影响后续操作先说清楚。第一个是仓库名称和路径。名称建议用简短的小写英文单词组合比如blog-source、order-system-api不要用中文和空格不然 clone 地址里出现乱码或%20这种事真的会让人抓狂。第二个是公开还是私有。个人学习项目、敏感业务代码选私有想让别人能看到、能贡献或者想拿来当作品集展示选公开。注意仓库设为公开后代码就对所有人可见了放之前检查一下有没有把密钥、密码、token 等敏感信息提交进去。第三个是初始化内容。你可以选择是否自动生成 README、.gitignore 和开源许可证。我的经验是如果你手里已经有代码建议创建空仓库不要勾选初始化选项避免和本地仓库产生冲突省得再去处理git pull合并问题如果你是从零开始可以勾上 README 和 .gitignore方便仓库一创建就有基本的结构。3.2 命令行上传一步步拆解假设你本地已经有一个项目文件夹里面是代码现在要传到 Gitee。打开终端进入项目目录依次执行git init这一步把当前目录变成一个 Git 仓库。注意它只会影响当前目录不会动上级目录。接着添加所有文件到暂存区git add .如果只想添加特定文件可以用git add 文件名。我建议第一次提交前先用git status看一眼确认没有把node_modules、target、.idea这类不该提交的目录加进来。提交到本地仓库git commit -m feat: 初始化项目基础结构提交信息建议用feat、fix、docs这类前缀后面跟简短描述历史记录看起来会非常清爽。然后添加远程仓库地址。比如你在 Gitee 上创建的仓库地址是gitgitee.com:yourname/my-project.gitgit remote add origin gitgitee.com:yourname/my-project.git如果提示remote origin already exists说明之前已经配过远程地址可以用下面的命令改成新的git remote set-url origin gitgitee.com:yourname/my-project.git推送前建议统一分支名。GitHub 默认新建仓库的主分支是mainGitee 新建仓库的主分支可能是master也可能在创建时让你选。先重命名本地分支保证和远程一致git branch -M main最后推送git push -u origin main-u的作用是把本地的main分支和远程的main分支关联起来以后直接执行git push或git pull就能对应到正确的分支。提示如果你的仓库在创建时选了master作为默认分支把命令里的main全部换成master即可。最稳的做法是推到远程后去 Gitee 仓库页面的管理里设置默认分支和本地保持一致。3.3 可视化方案不敲命令也能传不想记命令的话其实 IDEA 和 VS Code 都能完成全套推送。IDEA 里新建项目后打开下方的终端或直接使用顶部菜单Git-Gitee装了 Gitee 插件后可以直接分享项目到 Gitee。如果没装插件也可以用VCS-Import into Version Control-Share Project on GitHub这类入口但 Gitee 需要配置远程地址。我日常最常用的方式其实是首次推送用命令行搞定 remote 配置之后的日常提交推送全部在 IDEA 的Git面板里操作——右键项目选择Git-Commit Directory...填好提交信息再点Push按钮即可。这几步操作足够覆盖 90% 的日常场景。新手最容易犯的错是在 IDE 里提交时把Commit和Push分开点、又没注意分支名结果发现远程仓库里多了几个奇怪的分支。建议刚上手时每次提交都顺手Push保持远程仓库和本地一致等习惯之后再按自己节奏来。3.4 提交规范与仓库整洁度仓库能不能长期好用跟提交习惯直接相关。我踩过几次坑之后给自己定了几条原则每个提交只做一件事要么修 bug要么加功能不要混在一起提交信息用feat:、fix:、docs:、chore:等前缀方便后续生成 changelog不要提交生成物目录比如node_modules、dist、build、.gradle等大文件不要直接塞进仓库后面专门聊 LFS 怎么处理这些习惯看着不起眼但等你需要回滚版本、查找历史提交时就会发现整洁的提交历史是最大的省时间工具。4. Gitee 开源许可证怎么选合规这件事不能拍脑袋4.1 许可证到底管什么如果你准备把仓库设为公开就绕不开一个问题开源许可证选什么。很多新手以为许可证只是走个形式随便选一个 MIT 就行实际上许可证决定了别人能不能合法地使用、复制、修改和分发你的代码。简单说没有许可证的代码默认是保留所有权利别人即使能看到你的源码也没有合法权利去使用它。所以在 Gitee 上公开仓库时最好明确选择一个许可证这是对项目使用者负责也是对自己负责。4.2 主流许可证一表看懂我在 Gitee 上创建仓库时平台提供了常见的许可证模板选择前先用一张表看清楚区别许可证核心特点适合场景主要限制MIT极其宽松几乎无限制学习项目、库、个人作品保留版权声明即可Apache-2.0宽松含专利授权条款商业友好的开源项目保留声明注明修改GPL-3.0有传染性衍生作品必须开源希望防止别人闭源使用你的代码商用必须开源衍生代码AGPL-3.0比 GPL 更严网络服务也要开源服务端软件提供网络服务也需开源LGPL-3.0允许库被闭源商业项目链接动态链接的类库修改库本身需开源MPL-2.0文件级弱传染性兼顾商业与开源的组件修改过的文件需开源4.3 按场景选别上来就 MIT我自己的选择逻辑是这样的纯学习、笔记、示例代码用 MIT别人拿去随便用不用来咨询我。自己写的开源库希望被广泛采用但不介意被商业化用 Apache-2.0它自带的专利授权条款对商业使用者更友好。做的是客户端或服务端应用介意别人拿去闭源二次分发用 GPL-3.0。做的是 SaaS 服务特别在意服务端不能被私有化用 AGPL-3.0。一个容易被忽略的点是如果你的项目引用了其他开源代码而这些代码是 GPL 协议的那你整个项目大概率也只能用 GPL 系列。所以选许可证之前先确认你的依赖项都用了什么协议不然会有合规风险。这块我建议多花十分钟去查一下每个依赖的 LICENSE 文件别等服务上线被指出问题才补。4.4 实操在 Gitee 仓库里加上许可证如果你已经创建了仓库后续补许可证也很方便。在 Gitee 仓库页面的管理 - 基本信息里可以看到许可证设置也可以直接在本地仓库根目录添加一个LICENSE文件把许可证全文放进去然后推送。我的习惯是一个开源项目必须具备README.md、LICENSE、.gitignore三个文件。README 告诉别人这个项目是什么、怎么用LICENSE 告诉别人权利边界.gitignore 保证不该提交的东西不会进历史记录。这三个文件齐全项目的基本可信度就有了。注意许可证文本一定要从正规渠道复制不要手打因为许可证有严格的法律文本少一段多一段都可能导致协议失效。Gitee 创建仓库时自带的模板可以直接选也可以在官网获取标准文本。5. Gitee Pages把仓库变成可访问的站点5.1 Pages 能做什么Gitee Pages 是很多人忽略但非常实用的功能它能把你的仓库变成一个可以直接通过网址访问的静态网站。这意味着你可以把个人简历仓库变成在线简历把开源项目仓库变成项目文档站点把博客源码推上去让 Gitee 帮你托管生成后的静态页面。我自己就用它搭了一个项目文档站。写完代码、把文档 push 上去稍等一会儿就能通过https://用户名.gitee.io/仓库名/访问到文档页面。不需要自己买服务器不需要配置 Nginx对个人项目和文档型站点来说成本几乎为零。5.2 部署流程跟着做就行部署 Pages 的具体操作如下确保你的仓库里已经有一份构建好的静态文件比如index.html或者能生成静态站点的源码如 VitePress、Hexo、docsify 等打开仓库页面的服务-Gitee Pages选择要部署的分支比如master或main如果静态文件在子目录中在部署目录里填对应路径根目录则留空点击启动部署等待平台处理部署成功后页面会显示一个访问地址。如果显示 404大概率是部署目录填错了或者仓库里没有正确生成站点入口文件。我个人的做法是单独建一个docs目录放文档源文件用 VitePress 构建后把产物推到独立分支gh-pages或pages再指定该分支部署。这样做的好处是主分支保留源码部署分支只放产物结构清晰干净。5.3 绑定自定义域名的小细节如果你有自己的域名可以在 Pages 设置里绑定自定义域名。操作也不难把域名解析添加到 Gitee Pages 指定的地址平台会给出提示一般是 CNAME 解析记录然后在 Pages 设置里填入你的域名并提交即可。这里有一个我从实战中总结的坑解析配置后需要等待生效生效时间取决于你的 DNS 服务商从几分钟到几小时都可能。不要刚配置完发现访问不了就反复修改先ping一下域名确认解析生效再排查其他问题。5.4 Pages 踩坑实录仓库如果是私有的Pages 默认只能内部访问或者无法部署建议用公开仓库来部署 Pages站点文件必须放在指定分支和路径部署目录填错是常见的 404 原因如果需要 HTTPS平台一般会自动生成或提供证书配置入口绑定自定义域名后记得检查证书是否生效部署完成后发现内容没更新先看你的git push是否真的推到了部署分支另外Pages 站点适合静态页面场景不要试图在上面跑 PHP、Java 等后端逻辑它的定位就是托管静态资源。如果想要更多动态能力那就得另找服务了。6. 大文件上传Git LFS 的正确打开方式6.1 为什么大文件不能直接 push有次同事往仓库里塞了一个 200MB 的数据库备份文件git push的时候终端卡了五六分钟然后直接报错RPC failed; HTTP 413 curl 22。这就是 Git 本身的设计问题每次提交记录里都会保存这个文件的完整历史仓库体积瞬间膨胀后续每次 clone 都要拉这一大坨东西所有协作者都跟着遭殃。所以正规的做法是使用 Git LFSLarge File Storage。它把大文件的真实内容存储在单独的存储区域Git 仓库里只保留一个指针文件。这样仓库本身保持轻盈需要时才按版本拉取大文件。6.2 安装与配置Git LFS 是独立工具需要先安装。官网提供各系统的安装包Windows 有安装向导macOS 可以用 Homebrewbrew install git-lfs装好后在项目目录执行一次全局初始化git lfs install6.3 三步走追踪、提交、推送初始化完成后在项目根目录指定哪些文件需要用 LFS 管理git lfs track *.zip git lfs track *.mp4 git lfs track *.psd每执行一次git lfs trackGit 会自动生成或更新.gitattributes文件。这个文件会记录哪些类型的文件走 LFS需要一并提交到仓库git add .gitattributes git add 你的大文件 git commit -m feat: 添加设计源文件使用LFS git push -u origin main从这以后再往仓库里添加新的.zip、.mp4或.psd文件Git 都会自动把它们当作 LFS 对象处理你不需要重复执行track命令。6.4 大文件管理的注意事项与配额Gitee 的 LFS 服务有空间和流量配额限制具体数字以平台的帮助文档为准。个人使用一般够用但不要往仓库里堆几个 GB 的电影素材那既不合适也不够用。git lfs track的匹配规则支持通配符但要小心写错导致不该跟踪的文件被跟踪。建议追踪后执行git lfs status看一眼哪些文件被纳入了 LFS。LFS 只对之后提交的新文件生效如果你已经用普通方式提交过一个大文件可以用git lfs migrate重写历史但这会改动提交记录多人协作时要特别谨慎。clone 一个使用 LFS 的仓库时如果本机没有安装 Git LFS会得到一堆指针文本而不是真实文件。所以团队里要用 LFS 的仓库务必在 README 里写清楚请先安装 git-lfs。提示Gitee 帮助文档对 LFS 的用量限制有说明。建议在上传大量设计素材前先确认自己的配额避免推到一半被拒绝。7. 常见问题速查表我把这几年在 Gitee 使用过程中遇到的高频问题整理成一个速查表方便大家直接搜索对照问题现象常见原因解决方法拉取代码提示Permission denied (publickey)SSH 公钥未配置或配置错误重新生成密钥复制公钥到 Gitee 设置的 SSH 公钥中push 提示remote origin already exists远程地址已配置过用git remote set-url origin 新地址修改push 被拒绝failed to push some refs远程有本地没有的提交先git pull --rebase再尝试推送clone 后文件内容是指针文本本机未安装 git-lfs安装 git-lfs 后重新 clone 或执行git lfs pullPages 访问返回 404部署目录配置不正确或分支没选对检查部署目录、部署分支是否正确上传大文件时RPC failed未使用 Git LFS配置 Git LFS追踪对应文件类型后重新推送git push需要反复输密码使用了 HTTPS 地址改用 SSH 克隆地址并配置 SSH 密钥提交后发现误把密码提交进仓库敏感信息入仓立即撤销该提交并更换密码/token不要只删文件仓库里出现大量无意义提交提交粒度过大缺乏规范每次提交只做一件事信息用feat:、fix:等前缀IDEA 里找不到 Git 可执行文件系统未安装 Git安装 Git 后在 IDEA 设置里指定可执行路径分支名不一致导致 push 混乱本地主分支和远程默认分支不同用git branch -M main统一后推送还有几个我特别想强调的细节不要在公开仓库里提交任何密钥、密码、token一旦泄露立即吊销并轮换不要指望删除文件或提交就能解决历史记录里还有。多环境协作时建议在本地配置user.name和user.email避免提交记录里出现 A 电脑的作者名、B 电脑的作者名混用导致代码溯源困难。在 IDEA 或 VS Code 里操作 Git 时如果遇到奇怪的报错不妨切到命令行执行同样的命令通常能看到更详细的错误信息排查效率反而更高。8. 最后分享一点我的体会工具本身永远只是手段真正重要的是你能不能在一套稳定的协作流程里持续沉淀出属于自己的项目和经验。我用 Gitee 这几年最明显的变化是新成员上手快、代码交接成本低、个人项目随时有个稳妥的落脚点而且因为私有仓库免费很多从零开始的想法都可以先托管起来慢慢打磨。如果你还在 GitHub 和 Gitee 之间犹豫我的建议是国内业务团队或面向国内用户的项目直接用 Gitee 起步把 SSH 密钥、分支规范、许可证选择、Pages 部署、LFS 上传这五件事一次配好后面开发会非常省心。热爱国际开源的项目再考虑 GitHub 两边同步。工具没有高下之分适合当前场景的就是最好的能把代码安心放上去、持续迭代、让项目一天天成型这才是托管平台最核心的价值。