本地项目上传到GitHub--小怪教程（Git Bash实操+常见报错解决

一、前言

最近需要把本地项目上传到 GitHub，项目目录中包含前后端代码，例如：

jza-picture
├── jza-picture-backend
├── jza-picture-frontend
├── README.md
└── .gitignore

本文记录从本地初始化 Git 仓库、提交代码、创建 GitHub 仓库、推送代码，到解决推送过程中遇到的常见问题，附带命令表格、全套复制即用指令。

二、准备工作

需要提前安装：

• Git
• GitHub 账号
• 本地已有项目代码

安装 Git 后，在项目文件夹中右键一般会看到：

• Open Git GUI here
• Open Git Bash here

本文全程使用 Open Git Bash here 命令行操作。

三、确认要上传的项目目录

一定要进入真正要上传的项目根目录，区分正确 / 错误路径：

类型	路径示例	风险说明
✅ 正确根目录	E:\Star-projects\jza-picture	仅上传当前项目文件
❌ 错误上级目录	E:\Star-projects	会批量上传论文、压缩包、其他项目等无关文件

进入项目目录后右键打开 Git Bash，终端路径格式 /e/Star-projects/jza-picture 即目录无误。

四、添加 .gitignore 文件

在项目根目录创建 .gitignore 文件，过滤依赖、构建产物、日志、密钥等敏感文件，完整通用配置：

# OS / editor
.DS_Store
Thumbs.db
.idea/
.vscode/
*.iml

# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
pnpm-debug.log*

# Frontend
**/node_modules/
**/dist/
**/dist-ssr/
**/*.tsbuildinfo

# Backend
**/target/
**/build/
application-local.yml
**/application-local.yml

# Local packages / archives
*.zip
*.rar
*.7z

# Secrets
*SecretKey*
*secret*
*.pem
*.key

禁止上传文件清单：

• node_modules、dist、target 编译依赖包
• 密钥、本地配置、日志文件、压缩包

五、初始化 Git 仓库

在 Git Bash 中依次执行：

# 初始化本地Git仓库
git init
# 设置默认主分支为main
git branch -M main
# 查看文件变更状态
git status

执行 status 出现大量红色文件属于正常，代表文件未提交至本地仓库。

六、提交本地代码

# 将全部文件加入暂存区
git add .
# 提交代码并填写提交备注
git commit -m "Initial commit"

首次提交报错：未配置用户名邮箱解决

第一次使用 Git 会拦截提交，执行全局配置命令：

git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub绑定邮箱"
# 示例
git config --global user.name "test-user"
git config --global user.email "123456@qq.com"

配置完成后重新执行 commit 提交。

七、在 GitHub 创建远程仓库

打开官网：https://github.com 操作配置对照表：

配置项	设置要求
Repository name	和本地项目同名，例：jza-picture
仓库权限	Public（公开）/ Private（私有）自选
Add a README file	❌ 取消勾选
Add .gitignore	❌ 取消勾选
Choose a license	❌ 取消勾选

操作步骤：

1. 登录 GitHub
2. 右上角点击 + 号
3. 选择 New repository 新建仓库
4. 按照上表完成参数填写
5. 点击 Create repository

创建完成复制 HTTPS 仓库地址（下文统一使用占位符）：

https://github.com/你的用户名/你的仓库名.git

八、绑定远程仓库

回到 Git Bash，执行绑定命令：

git remote add origin https://github.com/你的用户名/你的仓库名.git
# 校验远程仓库绑定信息
git remote -v

输出如下内容代表绑定成功：

origin  https://github.com/你的用户名/你的仓库名.git (fetch)
origin  https://github.com/你的用户名/你的仓库名.git (push)

九、推送代码到 GitHub

# 首次推送，关联本地与远程main分支
git push -u origin main

第一次推送会弹出 GitHub 网页授权窗口，登录账号授权即可。推送成功后刷新仓库页面就能查看全部代码。

十、后续更新代码流程

仅首次推送需要 -u 绑定参数，后续修改更新简化命令：

git status
git add .
git commit -m "更新说明：修复bug/新增功能"
git push

补充：更换电脑拉取已有 GitHub 项目

新设备克隆远程仓库完整命令：

# 克隆代码到本地
git clone https://github.com/你的用户名/你的仓库名.git
# 进入项目目录即可正常修改推送

补充：新手常用撤销命令

# 撤销git add . 所有暂存文件
git reset .
# 修改上一次提交的备注信息
git commit --amend

十一、常见问题及解决方案

报错速查表

报错关键词	报错核心原因	修复操作命令
Permission denied (publickey)	使用 SSH 地址，未配置 SSH 密钥	git remote set-url origin https://github.com/你的用户名 / 你的仓库名.git git push -u origin main
SSL certificate unable to get local issuer certificate	Windows Git 证书校验失败	git config --global http.sslBackend schannel git config --global http.sslVerify true git push -u origin main
remote origin already exists	本地已绑定 origin 远程地址	git remote set-url origin https://github.com/你的用户名 / 你的仓库名.git git push -u origin main
src refspec main does not match any	本地无任何提交记录	git add . git commit -m "Initial commit" git branch -M main git push -u origin main

问题一：Permission denied (publickey)

报错信息

git@ssh.github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

原因

远程绑定的是 SSH 仓库地址，本地电脑未配置 GitHub SSH 密钥，无推送权限。

解决方案

新手推荐切换 HTTPS 地址，无需配置密钥：

# 查看当前远程地址
git remote -v
# 替换为HTTPS地址
git remote set-url origin https://github.com/你的用户名/你的仓库名.git
# 重新推送
git push -u origin main

问题二：SSL certificate unable to get local issuer certificate

报错信息

fatal: unable to access 'https://github.com/xxx/xxx.git/':
SSL certificate OpenSSL verify result: unable to get local issuer certificate (20)

原因

Windows 环境 Git 自带 OpenSSL 证书链缺失，HTTPS 证书校验失败。

推荐永久解决方案

git config --global http.sslBackend schannel
git config --global http.sslVerify true
git push -u origin main

临时应急方案（不建议长期使用）

git -c http.sslVerify=false push -u origin main

禁止全局永久关闭 SSL 校验，存在网络安全风险。

问题三：remote origin already exists

报错信息

error: remote origin already exists.

原因

本地仓库已经绑定过 origin 远程仓库，重复执行绑定命令冲突。

解决方案

git remote -v
git remote set-url origin https://github.com/你的用户名/你的仓库名.git
git push -u origin main

问题四：src refspec main does not match any

报错信息

error: src refspec main does not match any

原因

本地没有执行 commit 提交代码，本地无 main 分支记录。

解决方案

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

问题五：GitHub 页面刷新看不到代码

可能原因

1. 推送命令执行失败
2. 代码推送到其他分支
3. 远程仓库地址填写错误
4. 浏览器缓存未刷新页面

排查命令

git remote -v
git branch
git log --oneline
git push -u origin main

十二、完整命令总结

1、新项目首次上传全套命令

git init
git branch -M main
git status
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/你的用户名/你的仓库名.git
git push -u origin main

2、远程地址错误 / 更换仓库重新绑定

git remote -v
git remote set-url origin https://github.com/你的用户名/你的仓库名.git
git push -u origin main

3、SSL 证书报错专用修复命令

git config --global http.sslBackend schannel
git config --global http.sslVerify true
git push -u origin main

十三、总结

本地项目上传 GitHub 完整 8 步流程：

1. 进入项目根目录，编写.gitignore过滤无关文件
2. git init初始化本地 Git 仓库
3. git add .将全部代码加入暂存区
4. git commit提交代码至本地仓库
5. GitHub 官网创建空远程仓库，禁止勾选 README、gitignore
6. git remote add origin绑定远程仓库 HTTPS 地址
7. git push -u origin main首次推送全部代码
8. 后续修改代码直接执行git push更新

新手避坑要点：

1. 全程使用 HTTPS 仓库地址，规避 SSH 密钥权限报错；
2. Windows 系统遇到 SSL 证书报错，切换系统证书库即可根治；
3. 禁止提交密钥、本地配置、node_modules 等文件到远程仓库。