企业官网建设流程全解析

• 开发工具

git.push是 isomorphic-git 中用于把本地分支或标签推送到远程仓库的核心命令，覆盖了从参数解析、远程协商、对象打包到服务端响应解析的完整流程。本文以官方 API 文档（website/versioned_docs/version-1.x/push.md）为主体，结合 src/api/push.js、src/commands/push.js 与tests/test-push.js 中的实现与测试，系统讲解push的全部参数、返回值结构、认证方案、钩子回调以及底层协议细节。读完本文，你将能够正确配置push完成普通推送、强制推送、删除远端引用与标签推送，并理解 401 认证、非快进拒绝等常见场景的处理方式。

一、push 命令概览

push用于"Push a branch or tag"，即把一个本地分支或标签推送到远程仓库。与命令行 git 的git push对应，它同样支持--force、--delete语义，并额外提供了纯 JavaScript 环境下的回调式认证、进度上报与消息上报能力。

在 src/api/push.js 中，公开的push函数会先对fs、http、gitdir三个必选参数做断言校验，再通过discoverGitdir定位真实的 git 目录，最后调用内部实现_push：

assertParameter('fs', fs) assertParameter('http', http) assertParameter('gitdir', gitdir) const fsp = new FileSystem(fs) const updatedGitdir = await discoverGitdir({ fsp, dotgit: gitdir }) return await _push({ ... })

注意：dir在 API 层是可选参数，gitdir的默认值为join(dir, '.git')；ref在 API 层同样可选，缺省时使用当前检出的分支（见下文）。

二、完整参数表

原文档给出了push的完整参数清单，这里逐项继承并补充默认值与来源细节：

其中fs、http、gitdir是必选参数，缺一即抛出MissingParameterError。

参数解析顺序（来自源码）

在 src/commands/push.js#L70-L98 中，_push对关键参数的默认值解析顺序如下：

1. ref：_ref || await _currentBranch({ fs, gitdir })；若当前处于 detached HEAD 状态拿不到分支，抛出MissingParameterError('ref')。
2. remote：依次取remote参数、branch.<ref>.pushRemote、remote.pushDefault、branch.<ref>.remote，最后兜底'origin'。
3. url：url参数、remote.<remote>.pushurl、remote.<remote>.url；都取不到时抛出MissingParameterError('remote OR url')。
4. remoteRef：remoteRef参数，否则取branch.<ref>.merge（即配置的远程跟踪分支）。
5. corsProxy：参数未传时回落到配置键http.corsProxy。

这些配置键的取值逻辑意味着：你可以完全不传remote/url，只要仓库.git/config里配置了 remote 信息（正如tests/test-push.js#L21-L27 用setConfig写入remote.karma.url后直接push({ fs, http, gitdir, remote: 'karma' })），甚至什么都不传也能推送到默认 remote 的当前分支——测试用例 "push empty" 正是这种极简调用。

三、返回值：PushResult 与 RefUpdateStatus

push成功完成时返回一个Promise<PushResult>，即对本次推送操作结果的详细描述。原文档定义的类型如下：

type PushResult = { ok: boolean; error: string; refs: Object<string, RefUpdateStatus>; headers?: Object<string, string>; }

type RefUpdateStatus = { ok: boolean; error: string; }

原文档特别说明：如果没有错误，就不会有errors属性；ok消息与errors消息可能混合存在（多 ref 推送时部分成功、部分失败）。对应的 JSDoc 类型定义可以在 src/typedefs.js#L225-L237 中查到。

关于 ok / errors 数组语义

原文档还给出了一个补充表格，描述底层 report-status 响应中ok与errors数组的语义：

这正好对应 git receive-pack 协议中的 report-status 报文：服务端先返回一行unpack ok或unpack <error>，随后为每个 ref 返回一行ok <refname>或ng <refname> <error>。这些原始行在 src/wire/parseReceivePackResponse.js 中被解析：第一行写入result.ok/result.error，其余行按status(refAndMessage)拆解成result.refs[ref] = { ok, error }。headers字段则是在解析完成后，由 HTTP 响应头透传而来（见 src/commands/push.js#L282-L284）。

成功后的本地副作用

推送成功后，_push还会更新本地对远端分支的跟踪引用：若结果整体成功且该 ref 更新成功、且推送的不是 tag，则写入refs/remotes/<remote>/<branch>（删除时则删除该引用）。这一点在测试 "push" 中被验证：

expect(await resolveRef({ fs, gitdir, ref: 'refs/remotes/karma/master' })) .toEqual(await resolveRef({ fs, gitdir, ref: 'refs/heads/master' }))

而标签（refs/tags/*）不会在本地生成对应的 remote 跟踪 ref——测试 "push with lightweight tag" 与 "push with annotated tag" 都断言了refs/remotes/karma/refs/tags不存在（对应 issue #1900）。

四、实战示例

原文档给出的最小示例：

let pushResult = await git.push({ fs, http, dir: '/tutorial', remote: 'origin', ref: 'main', onAuth: () => ({ username: process.env.GITHUB_TOKEN }), }) console.log(pushResult)

在 Node 环境中http来自isomorphic-git/http（见测试中的import http from 'isomorphic-git/http'），在浏览器中则需配合 CORS 代理。下面按场景扩展几个可直接运行的变体。

1. 推送当前分支（最简形式）

await git.push({ fs, http, gitdir })

前提：仓库 config 中存在remote.origin.url且branch.<当前分支>.merge或同名分支约定成立，否则需要显式传remote/url/ref。

2. 推送到不同的远端分支名

await git.push({ fs, http, gitdir, remote: 'karma', ref: 'master', remoteRef: 'foobar', })

这会在远端创建refs/heads/foobar，对应测试 "push with ref !== remoteRef"：断言res.refs['refs/heads/foobar'].ok === true，且listBranches能看到foobar。

3. 推送标签

await git.push({ fs, http, gitdir, remote: 'karma', ref: 'annotated-tag' })

轻量标签与附注标签均可推送，最终都写入refs/tags/<name>。

4. 强制推送

await git.push({ fs, http, gitdir, remote: 'origin', ref: 'main', force: true })

等价于git push --force，用于覆盖非快进更新（详见第六节的非快进检查逻辑）。

5. 删除远端引用

await git.push({ fs, http, gitdir, remote: 'karma', remoteRef: 'foobar', delete: true })

等价于git push --delete，内部会把要推送的 oid 置为零哈希0000000000000000000000000000000000000000（见 src/commands/push.js#L100-L103），并在onPrePush的localRef.ref中以'(delete)'标识。

五、认证：从 URL 内嵌凭证到 onAuth 回调链

推送（以及对私有仓库的 clone / fetch）通常需要认证。git 全部使用 HTTPS Basic Authentication 完成认证，docs/authentication.md 给出了浏览器环境下的标准做法：直接构造带用户名密码的 URL。

// 这会构造出类似 https://user:password@github.com/isomorphic-git/isomorphic-git 的 URL， // 并且自动转义所有非 URL 字符 const repoUrl = "https://github.com/isomorphic-git/isomorphic-git" const u = new URL(repoUrl) u.username = login // 你的 GitHub 用户名 u.password = token // 来自 GitHub OAuth 流程，或（未开启 2FA 时）真实密码 await git.push({ fs, http, dir: '/yours', corsProxy: 'https://cors.isomorphic-git.org', url: u.toString(), })

需要注意的坑：

• 开启了两步验证（2FA）的账号，通常无法用普通用户名 + 密码推送，需要改用 Personal Access Token（Bitbucket 中称为 App Password）作为密码。测试 "push with Basic Auth credentials in the URL" 验证了http://testuser:testpassword@host/...这种 URL 内嵌凭证的推送方式。
• 第三方应用通过 "Login with GitHub" 等流程拿到的OAuth2 token，在授权范围内同样可作为password用于推送与拉取（GitHub / GitLab / Bitbucket 均采用这种用法）。

onAuth / onAuthFailure / onAuthSuccess 回调链

push支持三个认证回调（类型定义见 src/typedefs.js#L153-L171）：

• onAuth(url, auth)：在请求需要认证时被调用（首次发现 URL 不含凭证时触发），返回{ username, password }或{ headers }，也可以返回{ cancel: true }表示取消（此时抛出UserCanceledError而非HttpError）。
• onAuthFailure(url, auth)：在收到 401（"Authentication Required"）时触发，可返回新的凭证或自定义 headers 重试。测试 "onAuthFailure" 演示了两次失败后改用headers: { Authorization: 'Bearer Big Bear', 'X-Authorization': 'supersecret' }继续尝试的场景。
• onAuthSuccess(url, auth)：认证成功后触发，适合缓存凭证。

测试 "onAuth + cancel" 验证了onAuth返回{ cancel: true }时抛出UserCanceledError；测试 "onAuthFailure then onAuthSuccess" 则演示了失败回调返回正确密码后最终成功，且onAuthSuccess收到最终生效的凭证。若始终无法通过认证，最终会抛出包含401的HttpError（测试 "throws an Error if no credentials supplied" / "invalid credentials" 均断言错误消息包含401）。

在实现层面，src/commands/push.js#L106-L117 通过addCredentialUsername({ config, onAuth })包装了这些回调，使 config 中已有的用户名（例如 URL 内嵌的user:pass@）能在回调中作为初始值透传。

六、onPrePush 钩子：推送前的最后把关

onPrePush是推送请求发出前调用的钩子，收到的参数结构（src/typedefs.js#L267-L278）：

type PrePushParams = { remote: string; // 目标 remote 的名称 url: string; // 目标 remote 的 URL localRef: ClientRef; // 客户端希望推送的 ref 及其 oid remoteRef: ClientRef; // 远端已知的 ref 及其 oid }

回调返回false（或 Promise<false>）即可取消本次推送，此时_push抛出UserCanceledError（src/commands/push.js#L144-L152）。测试 "onPrePush abort" 验证了这一行为。测试 "push" 给出了真实的钩子入参样例：

onPrePush: [ { localRef: { oid: 'c03e131196f43a78888415924bcdcbf3090f3316', ref: 'refs/heads/master' }, remote: 'karma', remoteRef: { oid: '5a8905a02e181fe1821068b8c0f48cb6633d5b81', ref: 'refs/heads/master' }, url: 'http://localhost:8888/test-push-server.git', } ]

删除推送时localRef.ref为'(delete)'且oid为零哈希。这可以用于实现 CI 前置检查、权限校验等业务逻辑。

七、底层实现：一次推送在 isomorphic-git 内部的完整旅程

_push（src/commands/push.js）的执行流程可以概括为以下阶段：

1. 解析 ref 与 remote：确定ref（默认当前分支）、remote、url、remoteRef，并读取http.corsProxy配置（见第二节）。
2. 解析本地对象 ID：通过GitRefManager.expand把短 ref 名展开为完整引用（如master→refs/heads/master），再resolve得到要推送的oid；删除场景下oid为 40 个零。
3. 发现远端：通过GitRemoteManager.getRemoteHelperFor({ url })选择传输助手（HTTP 场景为 GitRemoteHTTP），以service: 'git-receive-pack'调用discover，获得远端 refs 与能力（capabilities）列表；认证回调在这一步注入。
4. 计算远端旧 oid 与目标 ref：oldoid = httpRemote.refs.get(fullRemoteRef) || 零哈希；若remoteRef在远端不存在，则按refs/前缀决定是完整引用还是refs/heads/<remoteRef>。
5. onPrePush 钩子：传入localRef/remoteRef/remote/url，返回 false 则取消。
6. 计算需要发送的对象集合（非删除时）：
   • 若远端已有该分支，先_findMergeBase找共同合并基点；
   • 通过listCommitsAndTags+listObjects计算从oid到 finish 点之间本地独有的对象；
   • thin-pack 优化：远端未声明no-thin能力时，跳过远端已知对象（共同合并基点、远端默认分支refs/remotes/<remote>/HEAD指向的对象），从而显著减小传输体积。
7. 快进（fast-forward）校验：若oid === oldoid直接置force = true；否则在未强制时检查：
   • 推送的是已存在的标签（refs/tags/*且oldoid非零）→ 抛PushRejectedError('tag-exists')；
   • 新提交不是旧提交的后代（_isDescendent为 false）→ 抛PushRejectedError('not-fast-forward')。 对应错误消息为 "Push rejected because tag already exists" / "because it was not a simple fast-forward"，并提示Use "force: true" to override.（见 src/errors/PushRejectedError.js）。
8. 能力协商：只发送服务端也支持的能力['report-status', 'side-band-64k', 'agent=...']。源码注释特别提醒：AWS CodeCommit 会在请求包含agent能力时中止推送，因此必须用filterCapabilities过滤。
9. 构造请求：src/wire/writeReceivePackRequest.js 按 pkt-line 协议写出命令序列——每行"{oldoid} {oid} {fullRef} \0 capabilities..."，首行携带能力声明，最后以 flush 包结尾；随后由_pack生成 packfile（删除时为空）。
10. 发送并解复用：GitRemoteHTTP.connect发送请求体，GitSideBand.demux把 side-band 通道分离为数据流与进度流；进度流按行喂给onMessage回调（测试 "push" 中收到的正是服务端post-receivehook 输出的 "Here is a message from 'post-receive' hook." 等消息）。
11. 解析响应：src/wire/parseReceivePackResponse.js 解析unpack ok/error首行与逐 ref 的ok/ng行，组装成PushResult；同时透传 HTTP 响应头到result.headers。
12. 收尾：更新本地refs/remotes/<remote>/<branch>；若整体失败或有单个 ref 失败，则抛出GitPushError，其data.prettyDetails以- {ref}: {error}逐行列出失败详情（见 src/errors/GitPushError.js）。

八、常见错误与处理建议

九、配套文档与测试资源

• 参数与类型：本命令类型定义见 src/typedefs.js#L225-L237（PushResult、RefUpdateStatus）与 src/typedefs.js#L267-L278（PrePushParams）
• 认证：docs/authentication.md、docs/onAuth.md、docs/onAuthFailure.md、docs/onAuthSuccess.md
• 钩子与回调：docs/onPrePush.md、docs/onMessage.md、docs/onProgress.md
• 环境依赖：docs/fs.md、docs/http.md、docs/headers.md、docs/cache.md、docs/dir-vs-gitdir.md
• 完整测试：tests/test-push.js（覆盖普通推送、极简调用、改名推送、两种标签、删除、认证成功/失败/取消、钩子中止、scp 地址报错等 14 个用例），服务端夹具位于tests/fixtures/test-push-server.git（含post-receivehook 消息）
• 协议实现：src/wire/writeReceivePackRequest.js、src/wire/parseReceivePackResponse.js

综上，git.push是一个能力完整、与原生 git 语义对齐的命令：既支持 URL 内嵌凭证与三回调认证链，也内置了 thin-pack 优化、快进校验与onPrePush钩子，返回值结构清晰可审计。无论是 Node 服务端脚本、浏览器端应用还是 CLI 封装，都可以直接复用它完成可靠的远端推送。

• 开发工具