在 React Native for OpenHarmonyRN-OH的开发实践中我选择了 TortoiseGit 这个可视化工具来完成代码的提交与推送。相比纯命令行它对 Git 新手更加友好也能让整个过程更直观。下面我将完整记录这次操作的全过程希望能帮到有同样需求的开发者。一、前期准备本地项目与远程仓库就绪我已经在本地完成了 RN-OH 项目的开发与调试代码可以正常运行。在 AtomGit 平台上创建了公开仓库react-native-oh-training并记录下了仓库的 HTTPS 地址https://atomgit.com/creaDelight/react-native-oh-training.git。记录下这串地址这是一会在TortoiseGit要填写的远端地址安装并配置 TortoiseGit确保已安装 TortoiseGit并完成了基础配置用户名、邮箱这些信息会作为代码提交的作者信息。在本地项目根目录右键选择TortoiseGit → Settings确认 Git 配置中的user.name和user.email与 AtomGit 账号信息一致。 这里对如何使用小乌龟也就是TortoiseGit不加赘述有很多文章有相关教程。AtomGit 代码托管全流程踩坑指南基于 TortoiseGit本章节对应代码分布式管理的全流程摒弃平铺直叙的步骤讲解完全以问题为导向拆解新手从本地仓库初始化到远程推送的每一个高频报错与解决方案同时保留 TortoiseGit 可视化工具的操作核心新手可直接对照避坑。一前期准备阶段的权限与配置避坑问题 1AtomGit 仓库关联后提示 “仓库不存在 / 权限拒绝”踩坑场景在 AtomGit 创建仓库后本地配置远程地址时提示仓库不存在或是推送时提示无权限访问。根因分析新手创建仓库时选择了私有属性但本地未配置正确的访问凭证或是仓库 HTTPS 地址复制错误多复制了空格、特殊字符导致地址失效也可能混用了 HTTPS 与 SSH 地址导致协议不匹配。解决方案正确复制仓库地址在 AtomGit 仓库主页点击「克隆 / 下载」选择 HTTPS 协议完整复制仓库地址确保地址末尾带有.git 后缀无多余空格私有仓库权限配置私有仓库必须创建个人访问令牌PAT用于身份验证操作路径AtomGit 个人中心 - 设置 - 个人访问令牌 - 创建令牌勾选 repo 仓库全量权限设置有效期后复制保存令牌仅显示一次仓库属性校验若为团队协作仓库需确认仓库管理员已为你的账号开通读写权限仅访客权限无法推送代码。问题 2TortoiseGit 安装后右键无菜单Git 配置不生效踩坑场景完成 TortoiseGit 安装后右键没有对应的 Git 操作菜单或是配置了用户名、邮箱后提交记录不生效。根因分析新手颠倒了安装顺序未先安装 Git for Windows 就直接安装 TortoiseGit导致工具缺少核心 Git 环境或是仅配置了项目级的用户名邮箱未配置全局配置导致提交信息异常。解决方案强制正确安装顺序先安装 Git for Windows完成安装后重启电脑再安装 TortoiseGit安装过程中自动关联 Git 环境全局配置校验在项目根目录右键选择 TortoiseGit → Settings → Git确认 user.name 与 user.email 已正确配置且与 AtomGit 账号的用户名、绑定邮箱完全一致配置生效验证打开 Git Bash执行git config --global --list查看配置信息是否正确确保全局配置生效。二本地仓库初始化的常见错误与修复问题 1初始化仓库后项目文件丢失 / 无法提交代码踩坑场景执行创建版本库操作后项目原有代码文件丢失或是提交时提示无文件可提交。根因分析新手误勾选了创建版本库时的「纯仓库」选项创建了无工作目录的裸仓库导致项目文件被重置或是在非项目根目录执行了初始化.git 文件夹生成在错误路径Git 无法识别项目文件。解决方案文件丢失紧急修复先备份项目剩余文件删除根目录下的.git 隐藏文件夹重新执行初始化操作正确初始化操作务必在 RN-OH 项目根目录与 package.json 同级空白处右键选择「Git 在这里创建版本库」弹出的窗口中不勾选任何选项直接点击 OK初始化成功后根目录会生成隐藏的.git 文件夹新手避坑操作初始化前务必完整备份项目代码Windows 系统开启「显示隐藏的项目」确认.git 文件夹在项目根目录即为初始化成功。问题 2提交时提示 “文件过大超出 Git 限制提交失败”踩坑场景第一次提交代码时提示文件大小超出限制提交中断无法完成本地提交。根因分析新手未配置.gitignore 文件导致 RN-OH 项目中的 node_modules 依赖包、harmony 编译 build 缓存、日志文件等大体积文件被纳入版本控制超出 Git 的单文件大小限制。解决方案先配置.gitignore 文件在项目根目录创建.gitignore 文件写入 RN-OH 项目专用忽略规则核心包含以下内容# 依赖目录 node_modules/ # 编译缓存 harmony/build/ android/build/ ios/build/ # 日志文件 *.log # 编辑器配置 .idea/ .vscode/ # 系统文件 .DS_Store Thumbs.db # 签名敏感文件 *.p12 *.jks清理已缓存的大文件若已执行过 add 操作执行git rm -r --cached node_modules命令将大文件从暂存区移除再重新执行提交操作。避坑指南必须先配置.gitignore 文件再执行第一次代码提交避免后续清理仓库历史大文件的复杂操作。三远程仓库关联的高频报错解决问题 1添加远程仓库时提示 “remote origin already exists”踩坑场景配置 AtomGit 远程地址时提示远程 origin 已存在无法添加新的远程仓库。根因分析项目之前初始化过 Git 仓库已配置过 origin 远程地址重复添加导致报错或是克隆过其他仓库原有远程地址未清理。解决方案先查看现有远程地址打开 Git Bash执行git remote -v查看已配置的远程仓库地址删除旧的远程地址执行git remote rm origin删除原有 origin 配置重新添加 AtomGit 地址在 TortoiseGit 设置 - 远端中填写远端名称 originURL 粘贴 AtomGit 仓库的 HTTPS 地址点击添加 - 保存即可。问题 2拉取远程代码时提示 “fatal: refusing to merge unrelated histories”踩坑场景关联远程仓库后第一次拉取代码时提示拒绝合并不相关的历史拉取失败。根因分析创建 AtomGit 远程仓库时勾选了「初始化 README、LICENSE、.gitignore」选项远程仓库已有独立的提交历史与本地仓库的提交历史无关联Git 默认拒绝合并。解决方案新手推荐方案删除已创建的 AtomGit 仓库重新创建空仓库不勾选任何初始化选项直接关联本地仓库推送从根源避免历史冲突现有仓库修复方案执行拉取命令时添加允许无关历史合并的参数命令如下bashgit pull origin master --allow-unrelated-histories合并完成后即可正常执行推送操作。四代码提交与推送的核心问题处理问题 1推送时提示 “authentication failed” 身份验证失败踩坑场景执行推送操作时弹出身份验证窗口输入 AtomGit 的账号登录密码后提示验证失败无法推送代码。根因分析这是新手托管代码的第一大高频坑 ——AtomGit 的 HTTPS 推送不支持账号登录密码必须使用前文创建的个人访问令牌PAT作为密码进行身份验证或是 Windows 凭据管理器缓存了错误的账号信息导致验证持续失败。解决方案正确身份验证方式弹出验证窗口时用户名填写 AtomGit 的账号名密码栏必须粘贴之前创建的个人访问令牌PAT而非账号登录密码清理错误缓存凭证打开 Windows 控制面板 - 凭据管理器 - Windows 凭据删除所有 AtomGit 相关的缓存凭据重新执行推送操作输入正确的账号与 PAT 令牌令牌权限校验确认 PAT 令牌已勾选 repo 仓库的所有读写权限且令牌未过期过期后需重新创建。问题 2推送时提示 “failed to push some refs to 远程地址”踩坑场景本地提交成功执行推送时提示推送失败无法将本地分支推送到远程仓库。根因分析远程仓库有本地不存在的提交内容比如远程新增了 README 文件本地分支落后于远程分支Git 为了避免覆盖远程代码直接拒绝了推送请求。解决方案先拉取远程最新代码在项目根目录右键选择 TortoiseGit → Pull拉取远程仓库的最新代码若有冲突先完成冲突解决变基处理避免分叉新手推荐使用 rebase 模式拉取执行git pull origin master --rebase将本地提交拼接到远程提交之后避免分支分叉重新执行推送拉取合并完成后再次右键选择 TortoiseGit → Push保持本地分支与远端分支一致点击确定即可完成推送。避坑指南每次推送代码前必须先拉取远程最新代码解决冲突后再推送养成 “先拉后推” 的习惯。问题 3推送成功后AtomGit 仓库看不到提交记录 / 提交者不显示踩坑场景TortoiseGit 提示推送成功但 AtomGit 仓库主页看不到提交记录或是提交记录没有关联到自己的账号。根因分析一是本地推送的分支与 AtomGit 仓库的默认分支不一致比如本地是 master 分支远程默认分支是 main推送到了非默认分支主页无法直接查看二是本地配置的 user.email 与 AtomGit 账号绑定的邮箱不一致提交记录无法关联到账号。解决方案分支匹配校验在 AtomGit 仓库的分支列表中查看是否有本地推送的 master 分支可在仓库设置中将 master 设置为默认分支即可在主页查看提交记录邮箱配置校验核对本地 Git 配置的 user.email必须与 AtomGit 账号绑定的邮箱完全一致不一致的话执行以下命令修改全局配置bashgit config --global user.email 你的AtomGit绑定邮箱后续提交即可正常关联到 AtomGit 账号显示正确的提交者信息。二、具体流程在 RN-OH 项目根目录空白处右键点击进入文件夹内然后右键创建版本库在弹出的窗口中不勾选 选项点击OK完成本地仓库的创建。此时项目目录下会生成一个隐藏的.git文件夹这是 Git 管理代码的核心目录。三、添加远程仓库地址在项目根目录右键选择 设置在git凭证位置填入你注册的时候用的用户名和邮箱在远端窗口中将之前码云或者你github上面的那串复制的地址写入url以及推送url里面先点击添加/保存直接确定。在 “Remote” 输入框中填写origin这是 Git 默认的远程仓库别名在 “URL” 输入框中粘贴 AtomGit 仓库的 HTTPS 地址。点击OK保存这样本地仓库就和远程 AtomGit 仓库建立了关联。四、第一次提交与推送添加文件到本地主分支在项目根目录右键选择TortoiseGit → 提交在弹出的窗口中全部会选中所有文件点击OK将所有代码文件添加到 Git 暂存区。PS这里建议创建一个新分支一般在团体协助中会在新分支创建自己的分支待其他团队成员审核后才进行下一步合并到主分支这里只有我一人就直接提交到主分支了。推送到 AtomGit 远程仓库在项目根目录右键选择TortoiseGit → Push。在 “Push” 窗口中默认的远程仓库是origin分支是master保持默认设置点击OK。此时会弹出身份验证窗口输入你的 AtomGit 账号和密码或个人访问令牌点击OK开始推送。等待推送完成当窗口显示 “Success” 时说明代码已成功上传到 AtomGit 仓库。五、后续开发与版本管理日常开发提交后续开发中每次完成一个功能或修复一个 bug都可以通过TortoiseGit → Commit提交到本地仓库。建议遵循 Angular Commit Message 规范比如plaintextfix: 修复 Index.ets 中 logger 初始化问题 docs: 更新 README 中的部署步骤同步远程仓库定期通过TortoiseGit → Pull拉取远程仓库的最新代码避免冲突。如果需要开发新功能建议创建新分支TortoiseGit → Create Branch开发完成后再合并到主分支。六、总结与心得小心得只有提交到本地之后才能推送到远端不要颠倒顺序。通过 TortoiseGit 这个可视化工具我无需记忆复杂的 Git 命令就完成了从本地项目初始化到远程仓库推送的全流程。这对于 Git 新手来说非常友好也让我能更专注于 RN-OH 项目的开发本身。在 AtomGit 上的公开仓库希望这篇记录能帮助更多开发者顺利完成代码的版本管理与推送。也希望这篇文章能对正在尝试鸿蒙跨平台开发的同学有所帮助也欢迎大家在评论区交流踩坑经验。欢迎加入开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net