GitHub 项目维护实用指南

概述

GitHub 不仅是代码托管平台，更是现代软件开发的项目管理中枢。从仓库创建到自动化部署，每一个环节都有值得掌握的技巧和容易踩的坑。这份笔记整理了实际项目中积累的维护经验。

一、仓库生命周期管理

创建仓库的关键决策

创建仓库时有三个选择影响后续整个工作流：

重命名与迁移

仓库重命名后需要同步更新两处：

# 1. 本地 remote 地址更新
git remote set-url origin https://github.com/{user}/{new-name}.git

# 2. Vercel 重新连接新仓库地址
# 在 Vercel Dashboard → Settings → Git → 重新选择仓库

踩坑记录：GitHub 重命名仓库后，旧 URL 会自动 301 重定向到新 URL，所以 git push 不会直接报错，只会看到一条迁移提示。但 Vercel 那边的连接会断开，需要手动重新关联。

仓库迁移（Transfer）

将仓库从一个账号转移到另一个账号或组织时：

1. Settings → Danger Zone → Transfer ownership
2. 确认后仓库 URL 变为 github.com/{new-owner}/{repo}
3. 本地 remote 需要全部更新
4. 所有关联服务（Vercel、CI/CD）需要重新授权

二、Git 本地配置

多账号管理

同一台机器可能需要切换不同 GitHub 账号：

# 查看当前配置
git config user.name
git config user.email

# 项目级配置（仅当前仓库生效）
git config user.name "MYhao"
git config user.email "g3260089513@gmail.com"

# 全局配置（所有仓库默认）
git config --global user.name "your-name"
git config --global user.email "your@email.com"

项目级配置优先级高于全局配置。在多账号场景下，每个项目单独设置 user.name 和 user.email 是最安全的做法。

认证方式

推荐使用 GitHub CLI (gh) 或 SSH Key 进行认证，避免每次输入密码：

# SSH 方式
git remote set-url origin git@github.com:user/repo.git

# gh CLI 方式（首次使用需 gh auth login）
gh auth login

三、Commit 规范

Conventional Commits

本项目采用约定式提交格式：

<type>: <description>

<optional body>

常用 type：

Commit 粒度

• 一次 Commit 做一件事：避免"修复了A问题 + 顺便重构了B模块 + 更新了依赖"
• Commit message 说清楚为什么：fix: header scroll detection on mobile 比 fix: bug 有用 100 倍
• WIP Commit 先 squash 再合入主分支：保持历史干净

四、分支与协作

个人项目的轻量分支策略

main          ← 始终保持可部署状态
  ├── feat/xxx   ← 新功能开发
  ├── fix/xxx    ← Bug 修复
  └── exp/xxx    ← 实验性改动

个人项目不必搞 GitHub Flow 全套，但保持 main 分支随时可部署这个原则值得遵守。

冲突处理

# 拉取远端更新并 rebase
git pull --rebase

# 处理完冲突后继续
git add .
git rebase --continue

# 如果是完全不相关的历史（如远端有 Initial commit）
git pull --rebase --allow-unrelated-histories

踩坑记录：--force push 被 GitHub 安全分类器拦截。解决方案是用 git pull --rebase --allow-unrelated-histories 合并远端历史，而非暴力覆盖。

常用操作速查

# 创建并切换到新分支
git checkout -b feat/new-feature

# 查看所有分支
git branch -a

# 删除本地分支
git branch -d feat/done

# 合并分支到 main
git checkout main
git merge feat/new-feature

# 查看提交历史（简洁格式）
git log --oneline --graph --all

# 撤销最后一次 commit（保留改动）
git reset --soft HEAD~1

# 暂存当前改动
git stash
git stash pop

五、Issue 跟踪

Issue 作为项目中枢

本项目使用 GitHub Issues 进行任务跟踪，配合 needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix 五标签体系。

Issue 标题格式建议：[模块] 简短描述，例如 [首页] 添加分页功能。

Issue 模板

在 .github/ISSUE_TEMPLATE/ 下创建模板文件，引导提交者（包括未来的自己）提供关键信息：

## 背景
<!-- 为什么要做这个改动 -->

## 期望行为
<!-- 完成后的效果 -->

## 技术约束
<!-- 如果有的话 -->

六、Vercel 部署联动

自动化部署流水线

本地写代码 → git commit → git push → Vercel 自动检测 → 构建 → 部署

零手动操作，push 即部署。Vercel Dashboard 可看到每次部署的构建日志和预览 URL。

常见问题排查

生产域名绑定

1. Vercel Dashboard → Domains → 添加自定义域名
2. DNS 添加 CNAME 记录指向 cname.vercel-dns.com
3. 等待 SSL 证书自动签发（约 1-2 分钟）

七、日常维护清单

每周

• 查看 GitHub Issues，关闭已完成的、标记 needs-triage 的新 Issue
• 检查 Dependabot 或安全告警（Security → Dependabot alerts）

每月

• 检查依赖更新（npm outdated 或 Dependabot PR）
• Review 未合并的分支，删除已废弃的
• 备份重要数据（GitHub 的 .md 文档等）

每次大改动后

• 更新 README.md（如果新增了功能或改变了启动方式）
• 更新 CLAUDE.md（如果架构或命令有变化）
• 确认 Vercel 部署成功且线上功能正常

关键经验

1. 项目级 Git 配置优于全局配置。多账号场景下，每个项目单独配置 user.email 可以避免提交者信息错乱。
2. Commit message 是写给三个月后的自己看的。写清楚"为什么改"比"改了什么"更重要。
3. Public 仓库 + Vercel Hobby = 零成本个人站点部署方案。不需要服务器，不需要 CI 配置，push 即上线。
4. Issue 标签体系不需要一开始就完美。从 3-5 个标签开始，用着用着就知道需要什么了。
5. git pull --rebase 比 git pull 产生更干净的历史，值得养成习惯。
6. 不要 --force push 到 main。GitHub 的安全分类器会拦截，而且这个习惯本身就很危险。