如何把本地项目上传到 GitHub 仓库（完整教程）

很多同学第一次上传项目时，最容易卡在三件事：

• 没初始化 Git
• 远程仓库地址配错
• 首次认证失败（SSH key / Token）

这篇教程按「从 0 到可用」整理，跟着做一遍就可以把自己的项目稳定上传到 GitHub。

0. 准备工作#

先确认你已经安装好 Git：

git --version

如果能看到版本号（例如 git version 2.x.x），就可以继续。

1. 在 GitHub 上创建空仓库#

1. 打开 GitHub，点击右上角 + -> New repository
2. 填写仓库名（例如 my-first-project）
3. 选择 Public 或 Private
4. 先不要勾选 Add a README file（避免和本地历史冲突）
5. 点击 Create repository

创建后页面会给你一个仓库地址，通常有两种：

• HTTPS：https://github.com/你的用户名/仓库名.git
• SSH：git@github.com:你的用户名/仓库名.git

2. 本地项目初始化 Git#

进入你的项目目录，然后执行：

git init
git add .
git commit -m "init: first commit"

如果你还没有配置 Git 身份，先设置（只需一次）：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

3. 添加 .gitignore（强烈建议）#

上传前，建议把不该入库的文件排除掉，比如依赖、构建产物、环境变量。

常见示例（按你的项目类型调整）：

node_modules/
dist/
.env
.DS_Store

如果你在 git add . 之前忘了加 .gitignore，先补上，然后再执行一次：

git add .
git commit -m "chore: add gitignore"

4. 绑定远程仓库并推送#

把 origin 指向你刚创建的 GitHub 仓库：

git remote add origin <你的仓库地址>

查看是否添加成功：

git remote -v

然后推送：

git branch -M main
git push -u origin main

首次成功后，后续只需要：

git add .
git commit -m "feat: your message"
git push

5. 认证方式选择：HTTPS 还是 SSH#

方式 A：HTTPS（简单）#

优点：配置快。

注意：GitHub 不再支持账号密码直登，通常要用 Personal Access Token。

git push 后提示输入 password，应该填什么？#

如果你的远程地址是 HTTPS（https://github.com/...），这里的 password 不是 GitHub 登录密码，而是 Personal Access Token (PAT)。

1. GitHub 右上角头像 -> Settings
2. Developer settings -> Personal access tokens
3. 选择 Tokens (classic)（新手更容易上手）
4. 点击 Generate new token，勾选 repo 权限
5. 生成后复制 token（只显示一次）
6. 下次 git push 时输入：
   • Username：你的 GitHub 用户名
   • Password：刚才生成的 PAT

可以先确认远程地址类型：

git remote -v

如果显示的是 https://github.com/...，就一定要用 PAT。

方式 B：SSH（推荐长期使用）#

1. 生成密钥：

ssh-keygen -t ed25519 -C "your_email@example.com"

2. 拷贝公钥内容（~/.ssh/id_ed25519.pub）
3. 到 GitHub -> Settings -> SSH and GPG keys -> New SSH key
4. 添加后测试：

ssh -T git@github.com

看到 Hi <username>! 类似提示说明配置成功。

6. 常见报错与解决#

remote origin already exists#

说明你之前加过远程地址：

git remote remove origin
git remote add origin <你的仓库地址>

src refspec main does not match any#

通常是你还没提交过代码。先提交一次：

git add .
git commit -m "init"
git branch -M main
git push -u origin main

Permission denied (publickey)#

说明 SSH 密钥未配置好。按上面的 SSH 步骤重新检查：

• 本地是否有密钥文件
• GitHub 是否已添加公钥
• 远程地址是否为 SSH 格式

rejected / non-fast-forward#

远程有新提交，本地没同步：

git pull --rebase origin main
git push

7. 最小工作流（记住这 3 行）#

日常开发最常用：

git add .
git commit -m "feat: 描述你这次改了什么"
git push

到这里，你的项目已经可以稳定托管在 GitHub 上了。后续再学习分支协作（git checkout -b）、Pull Request、CI/CD 就会顺很多。