第一次把自己的项目发布到 GitHub 时我像个刚学会走路的孩子既兴奋又忐忑。本以为是一次简单的代码备份没想到却演变成了一场“斗智斗勇”的冒险。从神秘的红色报错到 GitHub 的大文件限制再到 master 与 main 分支的历史谜团我几乎踩遍了新手可能遇到的所有坑。今天我把这段从本地代码到云端开源的实战经历毫无保留地分享出来。希望这份带着“血泪”的指南能帮你避开那些让我抓狂的雷区。坑点一被垃圾文件污染的“公开处刑”我曾犯过一个极其低级的错误在 git add . 之后才想起来检查 .gitignore。结果几百兆的 node_modules 依赖包、IDE 的配置文件甚至连着我数据库密码的 .env 文件全都被我“打包”送上了公开仓库。避坑指南在 git init 之后、git add 之前第一件事永远是检查并完善 .gitignore把它当成你上传前的“安检门”。如果你不幸已经把敏感信息提交了千万别以为删掉文件就万事大吉必须使用 git filter-branch 或 BFG Repo-Cleaner 彻底清洗历史记录否则你的密钥随时可能变成黑客的狂欢券。坑点二撞上 GitHub 大文件的“天花板”当我试图上传一个包含演示视频的项目时终端在漫长的沉默后无情地抛出了 Large files detected 错误。原来 GitHub 对单个文件有 100MB 的严格限制我的 1.2GB 视频直接撞上了这堵叹息之墙。避坑指南对于必须进行版本控制的大文件如视频、数据集不要硬刚请召唤官方推荐的“驯兽师”——Git LFS (Large File Storage)。安装后只需执行 git lfs track “*.mp4”LFS 就会自动接管大文件的存储让推送重新畅通无阻。坑点三神秘的“网络重置”玄学在上传稍大一点的项目时终端经常卡在 Connection was reset 或 Could not connect to server。这通常是本地网络环境如代理、防火墙干扰了默认的 HTTPS 协议。避坑指南既然 HTTPS 这条路这么坎坷不如换一条更专业、更稳定的“高速公路”——SSH 协议。配置好 SSH Key 后通过 git remote set-url origin gitgithub.com:… 切换连接方式。换上 SSH 后网络问题果然迎刃而解而且从此彻底告别了反复输入密码的烦恼。坑点四master 还是 main分支的历史谜团当我信心满满地执行 git push -u origin master 时GitHub 却提示分支不匹配。原来现在 GitHub 新建仓库的默认分支已经变成了 main而我本地还在固执地用着 master。避坑指南拥抱变化在推送前执行 git branch -M main将本地分支重命名为 main然后再 git push -u origin main一切就顺理成章了。进阶让开源更专业的“三板斧”经过几次“毒打”我总结出了一套标准化的上传流程让开源变得更专业清理先行彻底清理本地编译产物、日志和敏感配置给仓库“洗个澡”。规范提交拒绝使用 “update” 这种毫无意义的提交信息采用 “feat: 新增用户登录模块” 这种清晰的语义化规范。分支保护在 GitHub 设置中开启 main 分支保护强制要求通过 PR 合并并配置 GitHub Actions 进行自动化测试避免直接推送导致的“翻车”。开源不仅是一种技术分享更是一种工程素养的体现。希望这些带着“血泪”的经验能让你的 GitHub 之旅走得更稳、更远