背景与准备
作为开发者，将本地代码托管到远程仓库（如 GitHub）是版本控制的基础技能。这不仅方便备份，更是团队协作的前提。本文针对已有本地项目的用户，讲解如何将其首次完整上传到 GitHub 的空白远程仓库。这与 git clone 下载操作相反。
前提条件
- Git 环境：已安装 Git 并配置好全局用户信息（
user.name和user.email）。 - 账号：拥有有效的 GitHub 账号。
核心流程概览
- 初始化本地 Git 仓库。
- 添加并提交本地代码。
- 在 GitHub 创建空白远程仓库。
- 关联本地与远程仓库。
- 推送代码至远程。
核心操作流程
第一步：初始化本地仓库
进入你的项目根目录（注意不是父目录），在终端执行初始化命令：
cd /path/to/your/project
git init
这会在目录下生成隐藏的 .git 文件夹，标志着该目录已成为 Git 仓库。
第二步：暂存与提交
将所有文件添加到暂存区。通常建议配合 .gitignore 文件排除编译产物或日志：
git add .
git commit -m "Initial commit"
git add .：跟踪当前目录下的所有文件。git commit：将暂存区内容写入本地历史。提交信息应简明扼要，说明本次改动。
此时，本地仓库已就绪。
第三步：创建远程仓库
登录 GitHub，点击页面右上角的 + 号，选择 New repository。
- Repository name：填写仓库名，建议与本地项目相关。
- Visibility：根据需求选择 Public 或 Private。
- 关键设置：不要勾选 "Add a README file"、"Add .gitignore" 或 "Choose a license"。因为本地已有代码，我们需要一个完全空白的仓库来接收推送。
创建成功后，GitHub 会显示连接指令，请保留该页面的 URL 信息。
第四步：关联远程仓库
在 GitHub 页面找到类似以下的命令，复制并在本地终端执行：
git remote add origin https://github.com/你的用户名/你的仓库名.git
origin是远程仓库的标准别名。- 使用
git remote -v可验证关联是否成功。
第五步：推送代码
新创建的 GitHub 仓库默认主分支通常为 main，而旧版 Git 本地默认可能是 master。需先确认本地分支：
git branch
情况一：本地分支为 main 直接推送：
git push -u origin main
情况二：本地分支为 master
推荐先将本地分支重命名为 main 以统一规范：
git branch -M main
git push -u origin main
或者指定映射关系推送：
git push -u origin master:main
参数 -u (--set-upstream) 仅在首次推送时使用，设置后后续可直接运行 git push 和 git pull。
进阶处理
分支名称差异处理
若本地是 master 且不想改名，推送到远程 main 时需注意映射。但为了长期维护方便，建议统一为 main。
清理历史中的大文件
如果不小心将大文件（如数据库、编译输出）提交到了历史中，即使删除文件，仓库体积依然庞大。可使用 git-filter-repo 工具重写历史。
警告：此操作会改写历史，务必提前备份仓库！
- 安装工具：
pip install git-filter-repo - 执行清理（例如删除 dist/ 目录痕迹）：
git filter-repo --path dist/ --invert-paths --force - 强制推送：
git push --force origin main - 清理垃圾对象：
git gc --prune=now --aggressive
记得更新 .gitignore 文件，防止未来再次误传。
效率提升技巧
常用命令别名
在 ~/.gitconfig 中添加以下配置，可简化高频命令：
[alias]
st = status
co = checkout
br = branch
ci = commit
ciam = commit --amend
di = diff
dc = diff --cached
unstage = reset HEAD --
last = log -1 HEAD
ll = log --pretty=oneline --abbrev-commit --
lol = log --graph --decorate --pretty=oneline --abbrev-commit
pom = push origin main
plom = pull origin main
之后可用 git st 代替 git status，git pom 代替 git push origin main。
IDE 集成操作
PyCharm 等 IDE 内置了 Git 支持，适合图形化操作：
- Ctrl + V (或 Alt + `)：打开 VCS 操作弹窗。
- Ctrl + K：打开提交窗口，查看变更并编写信息。
- Ctrl + Shift + K：推送更改。
- Ctrl + T：拉取最新代码。
IDE 能直观展示文件状态和历史，对初学者友好。
总结
本地项目首次上传 GitHub 的核心路径是：
git init初始化。git add+git commit本地提交。- GitHub 创建空白仓库。
git remote add关联。git push推送。
掌握这一流程是使用 Git 进行版本控制的基石。随着熟练度提升，你将进一步探索分支管理、合并策略及标签等高级功能。