微信小程序Git远程仓库设置（GitHub）

概述

在微信开发者工具中，通过 Git 版本管理将小程序项目推送到 GitHub 远程仓库，需要完成 SSH 密钥配置 和 远程仓库设置 两个核心步骤。

推荐认证方式：使用 SSH Key（指定密钥） 方式认证，比 SSH Agent 更可靠，不依赖系统 ssh-agent 进程。

一、生成 SSH 密钥对

打开终端（Terminal），执行以下命令：

ssh-keygen -t ed25519 -C "你的GitHub邮箱@example.com"

按提示操作：

文件保存路径：直接回车，使用默认路径 ~/.ssh/id_ed25519
密码短语 (passphrase)：可设置也可留空

为什么用 ed25519？ ed25519 是 GitHub 推荐的最新算法，比传统的 rsa 更安全、更快。如果系统不支持，可改用 ssh-keygen -t rsa -b 4096。

生成后会在 ~/.ssh/ 目录下产生两个文件：

文件	说明
`id_ed25519`	私钥（绝对不能泄露）
`id_ed25519.pub`	公钥（添加到 GitHub 使用）

二、将公钥添加到 GitHub

2.1 查看并复制公钥

cat ~/.ssh/id_ed25519.pub

复制输出的全部内容。

2.2 在 GitHub 上添加

打开 GitHub → Settings → SSH and GPG keys → New SSH key
Title：随意填写（如 WeChat DevTools）
Key type：选择 Authentication Key
Key：粘贴刚才复制的公钥内容
点击 Add SSH key

三、配置 ~/.ssh/config（推荐）

3.1 创建或编辑 config 文件

nano ~/.ssh/config

3.2 写入以下内容

# ===== GitHub 配置 =====
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  UseKeychain yes    # 仅 macOS 需要，Windows/Linux 删掉这行

3.3 设置文件权限

chmod 600 ~/.ssh/config

权限必须为 600：SSH 要求 config 文件权限必须是 600（仅所有者可读写），否则会报错 Bad owner or permissions。

3.4 逐行解释

配置项	含义
`Host github.com`	匹配规则：当连接 `github.com` 时触发以下配置
`HostName github.com`	实际连接的主机地址
`User git`	使用 `git` 用户身份连接（GitHub 固定为 git）
`IdentityFile ~/.ssh/id_ed25519`	指定使用的私钥文件路径
`UseKeychain yes`	macOS 专用：将密钥存入系统钥匙串，重启后自动加载

3.5 多平台/多账号配置（进阶）

# ===== GitHub 主账号 =====
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github
  UseKeychain yes

# ===== Gitee =====
Host gitee.com
  HostName gitee.com
  User git
  IdentityFile ~/.ssh/id_ed25519_gitee
  UseKeychain yes

# ===== GitHub 副账号（通过别名区分）=====
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  UseKeychain yes

使用副账号时，克隆地址中的 github.com 替换为别名：

git clone git@github-work:workuser/repo.git

四、测试 SSH 连接

ssh -T git@github.com

首次连接会提示确认 GitHub 指纹，输入 yes。

成功输出：Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.
失败输出：Permission denied (publickey) → 检查公钥是否正确添加到 GitHub

五、微信开发者工具配置

5.1 配置认证方式

进入 版本管理 → 设置（齿轮图标）→ 网络和认证 → 认证方式：

选择 使用 SSH Key（指定密钥）：

字段	应填写的路径
公钥文件	`/Users/你的用户名/.ssh/id_ed25519.pub`
私钥文件	`/Users/你的用户名/.ssh/id_ed25519`
密码短语	生成密钥时设置的密码，没设置就留空

公钥 vs 私钥路径

公钥文件路径末尾必须有 .pub

私钥文件路径没有 .pub

混淆两者会导致 SSH Public key file not found 错误

5.2 配置远程仓库

进入 版本管理 → 远程标签 → 添加远程仓库：

字段	值
名称	`origin`
URL	`git@github.com:你的用户名/仓库名.git`

SSH URL 格式：GitHub SSH 地址格式为 git@github.com:用户名/仓库名.git，不要使用 HTTPS 格式（https://github.com/...）。

5.3 推送

点击推送，选择本地分支和远程分支，确认即可。

六、常见问题排查

6.1 错误速查表

错误信息	原因	解决方案
`Permission denied (publickey)`	公钥未添加到 GitHub 或密钥不匹配	重新检查第二步
`SSH Public key file not found`	微信工具中公钥路径填错	确保公钥路径以 `.pub` 结尾
`credentials callback max loop reached`	认证方式配置不当	改用「指定密钥」而非「SSH Agent」
`Bad owner or permissions`	config 文件权限过宽	执行 `chmod 600 ~/.ssh/config`
`Could not open a connection to your authentication agent`	ssh-agent 未启动	执行 `eval "$(ssh-agent -s)"`
macOS 重启后需重新 ssh-add	未配置 UseKeychain	确保 config 中有 `UseKeychain yes`，然后执行 `ssh-add --apple-use-keychain ~/.ssh/id_ed25519`

6.2 新建空仓库能否推送？

Q：远程仓库是新建的空仓库，能推送吗？

A：完全可以。 新建的空仓库没有任何提交记录，直接推送本地分支即可。GitHub 会在首次推送时自动创建对应的远程分支。

6.3 nano 编辑器快捷键

快捷键	功能
`Ctrl+O`	保存文件（WriteOut）
`Enter`	确认文件名
`Ctrl+X`	退出 nano
`Ctrl+C`	取消当前操作
`Ctrl+G`	查看帮助

七、完整操作流程图

微信图片_20260422190301_401_34.png

伞间岁月