03 · 版本管理与双远端

把本地内容用 git 管起来，同时推到 Gitee（中文圈）+ GitHub（部署用）。

一、为什么要双远端

远端	作用	必要性
Gitee	国内访问快，给中文圈朋友直接看仓库	视主题而定
GitHub	Vercel 唯一支持的 git 提供商之一	必须（要部署博客的话）

💡 如果只想给国内朋友看仓库不部署博客 → 只用 Gitee 即可。 💡 如果只想部署博客不在意中文仓库 → 只用 GitHub 即可。 💡 大多数情况两个都要 —— Gitee 给仓库受众，GitHub 给 Vercel。

二、本地 git 初始化

一次性配置 git（如果第一次用 git）

bash

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"
git config --global init.defaultBranch main

主题目录初始化

bash

cd ~/notes/我的主题
git init -b main

创建 `.gitignore`

最小 .gitignore（暂时还没用 VitePress 的话）：

.DS_Store
.vscode/
.idea/
*.log

VitePress 的完整版本见 templates/gitignore（GitHub 仓库）。

三、SSH 密钥（一次配置，长期使用）

检查现有密钥

bash

ls ~/.ssh/id_ed25519* 2>/dev/null

如果有 → 跳过。

生成新密钥

bash

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "你的邮箱" -f ~/.ssh/id_ed25519 -N ""

-N "" 是不设密码短语，方便自动推送。如果要加密码自己改。

配置 ~/.ssh/config

Host gitee.com
  HostName gitee.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

bash

chmod 600 ~/.ssh/config

💡 同一把钥匙开两扇门 —— 不需要为 Gitee 和 GitHub 各生成一把。

预加 known_hosts（避免首次连接的"yes/no"提示）

bash

ssh-keyscan -t ed25519,rsa,ecdsa gitee.com github.com >> ~/.ssh/known_hosts 2>/dev/null
chmod 644 ~/.ssh/known_hosts

四、Gitee 远端：API 自动化

Step 1：获取 Personal Access Token

https://gitee.com/profile/personal_access_tokens → 生成新令牌 → 必须勾选：user_info、projects、keys → 立即复制（只显示一次）

Step 2：保存 token 到本地

bash

mkdir -p ~/.config/gitee && chmod 700 ~/.config/gitee
echo '你的token' > ~/.config/gitee/token
chmod 600 ~/.config/gitee/token

Step 3：上传 SSH 公钥到 Gitee

bash

PUBKEY=$(cat ~/.ssh/id_ed25519.pub)
TOKEN=$(cat ~/.config/gitee/token)

python3 <<EOF
import json, urllib.request
data = json.dumps({
    "access_token": "${TOKEN}",
    "title": "$(hostname -s)",
    "key": """${PUBKEY}"""
}).encode()
req = urllib.request.Request(
    "https://gitee.com/api/v5/user/keys",
    data=data,
    headers={"Content-Type": "application/json"}
)
print(json.loads(urllib.request.urlopen(req).read()))
EOF

Step 4：创建仓库

bash

TOKEN=$(cat ~/.config/gitee/token)
NAME="my-topic"  # 仓库名（英文）
DESC="主题描述"
curl -s -X POST "https://gitee.com/api/v5/user/repos" \
  -H "Content-Type: application/json" \
  -d "{\"access_token\":\"${TOKEN}\",\"name\":\"${NAME}\",\"description\":\"${DESC}\",\"private\":false,\"auto_init\":false}"

⚠️ Gitee 默认创建私有仓库——即使 private: false 也可能被建成私有。需要再调一次 PATCH API 改成公开：

bash

USER="你的Gitee用户名"
curl -s -X PATCH "https://gitee.com/api/v5/repos/${USER}/${NAME}" \
  -H "Content-Type: application/json" \
  -d "{\"access_token\":\"${TOKEN}\",\"name\":\"${NAME}\",\"private\":false}"

Step 5：添加 remote 并推送

bash

git remote add origin git@gitee.com:你的Gitee用户名/${NAME}.git
git add -A
git commit -m "init: 主题初始化"
git push -u origin main

五、GitHub 远端：API 自动化

Step 1：获取 Personal Access Token

https://github.com/settings/tokens/new

Note：personal-blog-deploy
Expiration：90 days（或 No expiration）
Scopes：勾选
- ✅ repo
- ✅ admin:public_key
- ✅ read:user

立即复制（只显示一次）。

Step 2：保存到本地

bash

mkdir -p ~/.config/github && chmod 700 ~/.config/github
echo '你的token' > ~/.config/github/token
chmod 600 ~/.config/github/token

Step 3：上传 SSH 公钥到 GitHub

bash

PUBKEY=$(cat ~/.ssh/id_ed25519.pub)
TOKEN=$(cat ~/.config/github/token)

python3 <<EOF
import json, urllib.request
data = json.dumps({
    "title": "$(hostname -s)",
    "key": """${PUBKEY}"""
}).encode()
req = urllib.request.Request(
    "https://api.github.com/user/keys",
    data=data,
    headers={
        "Authorization": "token ${TOKEN}",
        "Accept": "application/vnd.github+json"
    }
)
print(json.loads(urllib.request.urlopen(req).read()))
EOF

Step 4：创建仓库

bash

TOKEN=$(cat ~/.config/github/token)
NAME="my-topic"
DESC="主题描述"

curl -s -X POST -H "Authorization: token ${TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/user/repos" \
  -d "{\"name\":\"${NAME}\",\"description\":\"${DESC}\",\"private\":false,\"auto_init\":false}"

💡 GitHub 默认就是公开的（如果你勾的是 private: false），不用像 Gitee 那样再 PATCH。

Step 5：添加 GitHub 为第二 remote

bash

USER="你的GitHub用户名"
git remote add github git@github.com:${USER}/${NAME}.git
git push -u github main

六、双推工作流

配置完成后的状态

bash

$ git remote -v
github  git@github.com:用户/repo.git (fetch)
github  git@github.com:用户/repo.git (push)
origin  git@gitee.com:用户/repo.git (fetch)
origin  git@gitee.com:用户/repo.git (push)

日常推送

bash

# 单独推
git push origin    # 推 Gitee
git push github    # 推 GitHub

# 一次推全部
git push --all

推荐设置：自动同时推

.git/config 里添加：

ini

[remote "all"]
    url = git@gitee.com:用户/repo.git
    url = git@github.com:用户/repo.git

这样：

bash

git push all main   # 一次推到两个远端

七、Commit message 规范（推荐）

借用 Conventional Commits：

feat: 添加新功能 / 新内容
fix: 修复 bug
docs: 改文档（不影响代码）
refactor: 重构（不改功能）
chore: 杂项（依赖更新、配置改动）

例：

feat: 第 1 局复盘
fix: 修复 vercel.json 输出目录配置
docs: 更新 README 内容索引
refactor: 博客 URL 改为英文路径

八、常见坑

坑 1：Gitee API 创建仓库时的可见性

如前述：默认私有，要 PATCH 改公开。

坑 2：SSH 测试连接的 exit code

bash

ssh -T git@github.com
# 输出 "Hi xxx! You've successfully authenticated..."
# 但 exit code 是 1（GitHub 说"我不提供 shell access"）

这是正常的——只要看到 "successfully authenticated" 就 OK。

坑 3：第一次推送没设置 -u

bash

git push           # ❌ 错误：fatal: The current branch main has no upstream branch.
git push -u origin main   # ✅ 正确：第一次需要 -u 关联
git push                  # ✅ 之后就能简化

下一步

仓库就位 → 04-vitepress.md 开始装 VitePress 搭博客。

03 · 版本管理与双远端 ​

一、为什么要双远端 ​

二、本地 git 初始化 ​

一次性配置 git（如果第一次用 git） ​

主题目录初始化 ​

创建 .gitignore ​

三、SSH 密钥（一次配置，长期使用） ​

检查现有密钥 ​

生成新密钥 ​

配置 ~/.ssh/config ​

预加 known_hosts（避免首次连接的"yes/no"提示） ​

四、Gitee 远端：API 自动化 ​

Step 1：获取 Personal Access Token ​

Step 2：保存 token 到本地 ​

Step 3：上传 SSH 公钥到 Gitee ​

Step 4：创建仓库 ​

Step 5：添加 remote 并推送 ​

五、GitHub 远端：API 自动化 ​

Step 1：获取 Personal Access Token ​

Step 2：保存到本地 ​

Step 3：上传 SSH 公钥到 GitHub ​

Step 4：创建仓库 ​

Step 5：添加 GitHub 为第二 remote ​

六、双推工作流 ​

配置完成后的状态 ​

日常推送 ​

推荐设置：自动同时推 ​

七、Commit message 规范（推荐） ​

八、常见坑 ​

坑 1：Gitee API 创建仓库时的可见性 ​

坑 2：SSH 测试连接的 exit code ​

坑 3：第一次推送没设置 -u ​

下一步 ​

💬 评论与建议

03 · 版本管理与双远端

一、为什么要双远端

二、本地 git 初始化

一次性配置 git（如果第一次用 git）

主题目录初始化

创建 `.gitignore`

三、SSH 密钥（一次配置，长期使用）

检查现有密钥

生成新密钥

配置 ~/.ssh/config

预加 known_hosts（避免首次连接的"yes/no"提示）

四、Gitee 远端：API 自动化

Step 1：获取 Personal Access Token

Step 2：保存 token 到本地

Step 3：上传 SSH 公钥到 Gitee

Step 4：创建仓库

Step 5：添加 remote 并推送

五、GitHub 远端：API 自动化

Step 1：获取 Personal Access Token

Step 2：保存到本地

Step 3：上传 SSH 公钥到 GitHub

Step 4：创建仓库

Step 5：添加 GitHub 为第二 remote

六、双推工作流

配置完成后的状态

日常推送

推荐设置：自动同时推

七、Commit message 规范（推荐）

八、常见坑

坑 1：Gitee API 创建仓库时的可见性

坑 2：SSH 测试连接的 exit code

坑 3：第一次推送没设置 -u

下一步