本教程面向零基础用户，详细讲解从零开始创建开源鸿蒙跨平台项目，并将其代码提交到AtomGit公开仓库的完整流程。

一、基础准备（环境配置）

1.1 安装必要软件

在开始之前，需要先安装以下软件：

开发前需安装以下必要软件，建议按顺序安装：

软件名称	版本要求	用途
Java Development Kit (JDK)	JDK 17	Java 运行环境
DevEco Studio	最新版本	鸿蒙应用开发 IDE
Git	最新版本	版本控制工具

---

（1）安装Git

• 下载地址: Git官网
• 安装步骤:
  1. 下载Windows版本的Git安装包
  2. 双击运行安装程序
  3. 一路点击"Next"使用默认配置即可
  4. 安装完成后，右键点击桌面，如果看到"Git Bash Here"选项，说明安装成功

（2）安装DevEco Studio

• 下载地址: DevEco Studio官网
• 安装步骤:
  1. 注册华为开发者账号
  2. 下载DevEco Studio安装包
  3. 双击运行，按照提示完成安装
  4. 首次启动时选择需要的SDK和API版本

💡 提示: 更详细的安装教程请参考：https://blog.csdn.net/Guang_how927/article/details/157468495

1.2 验证Git配置

安装完成后，需要配置Git的基本信息（用户名和邮箱），这些信息会在代码提交时被记录。

打开Git Bash

• 在桌面空白处右键
• 选择 “Git Bash Here”
• 会弹出一个黑色的命令行窗口

配置用户名

# 配置用户名（可以是你的真实姓名或昵称）
git config --global user.name "你的名字"

示例：

git config --global user.name "张三"

配置邮箱

# 配置邮箱（建议使用 GitHub/Gitee 注册邮箱）
git config --global user.email "your.email@example.com"

示例：

git config --global user.email "zhangsan@example.com"

验证配置

# 查看当前配置
git config --global --list

执行该命令后，应该能看到刚才配置的 user.name 和 user.email 信息。

---

二、AtomGit远程仓库准备

2.1 什么是AtomGit？

AtomGit是开源中国的Git代码托管平台，类似于GitHub和Gitee，用于存储和管理代码项目。

2.2 注册AtomGit账号

1. 打开AtomGit网站

   • 访问地址：https://atomgit.com/

2. 注册账号

   • 点击页面右上角的 “注册” 按钮
   • 填写用户名、邮箱和密码
   • 完成邮箱验证

3. 登录账号

   • 使用注册的账号和密码登录

2.3 创建公开仓库

进入新建项目页面

登录后：

• 找到页面右上角的 “+” 号或 “新建项目” 按钮
• 点击进入创建新项目页面

填写项目信息

在创建页面，需要填写以下信息：

配置项	推荐值	说明
仓库名称	Kuikly-demo	使用英文名称，与项目相关，不要包含特殊字符
仓库描述	开源鸿蒙跨平台项目示例	简短描述项目的用途
仓库类型	公开	便于分享和展示，公开仓库可以被所有人查看
初始化选项	如下表所示	可选项，建议勾选

初始化选项说明

选项	是否勾选	作用
README	✓	自动生成项目说明文件（建议勾选）
.gitignore	✓	选择Android或HarmonyOS模板，忽略构建产物
License	✓	选择开源许可证（如MIT License）

推荐配置示例：

仓库名称: Kuikly-demo
仓库类型: 公开
README: ✓
.gitignore: Android
License: MIT License

点击创建

填写完成后，点击 “创建” 或 “Create” 按钮，仓库创建成功。

2.4 配置SSH密钥（推荐）

配置SSH密钥后，后续提交代码时无需每次输入密码，更安全也更方便。

什么是SSH密钥？

SSH密钥是一种身份验证方式，包含两个文件：

• 私钥（id_rsa）：保存在本地，绝对不能泄露
• 公钥（id_rsa.pub）：上传到AtomGit，用于验证身份

生成SSH密钥对

1. 打开Git Bash（在桌面右键 -> Git Bash Here）

2. 执行生成命令

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

注意: 将 your_email@example.com 替换为你注册AtomGit时使用的邮箱
参考密钥帮助文档

3. 按回车确认默认设置

执行命令后，会看到以下提示：

Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/YourName/.ssh/id_rsa):

直接按回车键，使用默认路径保存密钥。

4. 设置密码（可选）

Enter passphrase (empty for no passphrase):

可以直接按回车不设置密码（更方便），或者输入一个密码（更安全）。

5. 生成成功

看到类似以下信息表示生成成功：

Your identification has been saved in /c/Users/YourName/.ssh/id_rsa
Your public key has been saved in /c/Users/YourName/.ssh/id_rsa.pub

获取公钥内容

1. 查看公钥内容

在Git Bash中执行：

cat ~/.ssh/id_rsa.pub

2. 复制公钥

• 命令会显示一长串以 ssh-rsa 开头的文本
• 选中并复制整行内容（从 ssh-rsa 开始到结尾）

示例公钥格式：

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC... your_email@example.com

将公钥添加到AtomGit

1. 登录AtomGit

2. 进入个人设置

   • 点击右上角头像
   • 选择 “设置”

3. 找到SSH公钥设置

   • 在左侧菜单找到 “SSH公钥” 或 “SSH Keys”
   • 点击进入

4. 添加公钥

   • 在"标题"栏输入一个标识名称（如 “我的电脑”）
   • 在"公钥"栏粘贴刚才复制的公钥内容
   • 点击 “添加” 或 “Add” 按钮

测试SSH连接

在Git Bash中执行测试命令：

ssh -T git@gitcode.com

第一次连接时会提示：

The authenticity of host 'gitcode.com' can't be established.
Are you sure you want to continue connecting (yes/no)?

输入 yes 并按回车。

连接成功的标志：
看到类似以下信息：

Welcome to GitCode, [你的用户名]!

⚠️ 注意: 上图显示的是连接GitHub的示例。实际连接GitCode时，欢迎信息会显示 Welcome to GitCode, [你的用户名]!

🎉 恭喜！ SSH密钥配置成功，现在可以免密码提交代码了。

---

三、本地工程搭建与初始化

3.1 克隆远程仓库到本地

获取仓库地址

1. 打开你创建的AtomGit仓库页面

2. 复制仓库地址

   • 在仓库页面找到 “克隆” 或 “Clone” 按钮
   • 选择 HTTPS 或 SSH 地址
   • 点击复制按钮

地址格式示例：

• HTTPS: https://gitcode.com/your_username/your_project.git
• SSH: git@gitcode.com:your_username/your_project.git

执行克隆命令

1. 打开Git Bash

2. 导航到想要存放项目的目录

# 例如：切换到桌面
cd ~/Desktop

3. 执行克隆命令

git clone https://gitcode.com/your_username/your_project.git

注意: 将仓库地址替换为你自己的仓库地址

4. 克隆成功

看到类似以下信息表示克隆成功：

Cloning into 'your_project'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (3/3), done.

💡 提示: 上图使用的是TortoiseGit图形界面工具。如果你使用Git Bash命令行，效果是一样的，命令执行成功后会显示类似信息。

5. 进入项目目录

cd your_project

3.2 使用DevEco Studio创建工程

步骤1：启动DevEco Studio

• 双击桌面上的DevEco Studio图标启动

步骤2：创建新项目

1. 选择"Create Project"

   • 启动后会看到欢迎界面
   • 点击 “Create Project”

2. 选择项目模板

   • 在左侧选择 “Empty Ability”（空模板）
   • 点击 “Next”

3. 配置项目信息

   • Project name: Kuikly-demo（与仓库名称保持一致）
   • Package name: 自动生成，如 com.example.kuiklydemo
   • Project location: 选择刚才克隆的仓库目录
   • Language: 选择 ArkTS（推荐）
   • Compatible SDK: 选择合适的API版本

4. 完成创建
   • 点击 “Finish”
   • 等待DevEco Studio自动配置和同步项目

步骤3：了解项目结构

DevEco Studio打开后，你会看到以下主要目录：

KuiklyDemo/
├── entry/              # 主模块
│   ├── src/
│   │   └── main/       # 源代码
│   │       ├── ets/    # ArkTS代码
│   │       ├── resources/  # 资源文件
│   │       └── module.json5  # 模块配置
│   └── build-profile.json5  # 构建配置
├── AppScope/           # 应用全局配置
├── oh-package.json5    # 依赖管理
├── build-profile.json5  # 项目构建配置
├── hvigor/             # 构建工具配置
└── .gitignore          # Git忽略文件配置

3.3 配置.gitignore文件

什么是.gitignore？

.gitignore 文件用于告诉Git哪些文件或目录不需要被提交到仓库，通常包括：

• 编译生成的文件
• 依赖包
• IDE配置文件
• 临时文件

检查.gitignore文件

1. 查看是否存在.gitignore

在Git Bash中执行：

ls -la

如果能看到 .gitignore 文件，说明已经存在。

2. 如果没有.gitignore文件

如果你的项目目录中没有 .gitignore 文件，需要手动创建：

# 在项目根目录创建.gitignore文件
touch .gitignore

3. 编辑.gitignore文件

使用文本编辑器（如VS Code、记事本）打开 .gitignore 文件，添加以下内容：

# 构建产物
build/
.idea/
.hvigor/
.ohpm/
node_modules/
.local/

# 日志文件
*.log

# 操作系统文件
.DS_Store
Thumbs.db

# 临时文件
*.tmp
*.swp
*~

提交.gitignore文件

如果创建了新的 .gitignore 文件，需要提交到仓库：

# 添加到暂存区
git add .gitignore

# 提交到本地仓库
git commit -m "feat: 添加 .gitignore 配置文件"

# 推送到远程仓库
git push origin main

3.4 生成访问令牌（用于HTTPS方式提交）

如果你没有配置SSH密钥，或者遇到SSH问题，可以使用HTTPS方式提交，但需要访问令牌。

什么是访问令牌？

访问令牌（Access Token）是代替登录密码的验证方式，更安全，权限更可控。

生成访问令牌

登录GitCode网页端

• 访问：https://gitcode.com/
• 使用AtomGit账号登录

进入个人设置

• 点击右上角头像
• 选择 “设置”

进入开发者设置

• 在左侧菜单找到 “开发者设置”
• 点击进入

选择个人访问令牌

• 点击 “个人访问令牌”
• 点击 “生成新令牌” 按钮

配置令牌

• 令牌描述: 输入一个描述，如 “DevEco Studio提交代码”
• 有效期: 选择过期时间（建议选择30天或更长时间）
• 权限勾选:
  • ✓ repo - 仓库全权限
  • ✓ read_user - 读取用户信息
• 点击 “生成”

复制令牌

• 生成后会显示一串字符，这就是你的访问令牌
• 重要: 令牌只会显示一次，请立即复制并妥善保存

使用访问令牌

当你执行 git push 命令时，Git会提示输入用户名和密码：

• 用户名: 输入你的AtomGit账号（用户名或邮箱）
• 密码: 粘贴刚才复制的访问令牌（注意：不是登录密码）

⚠️ 注意: 访问令牌只会显示一次，如果忘记了，需要重新生成。

---

四、代码提交与同步

1 查看Git状态

在项目根目录打开Git Bash，执行：

git status

这个命令会显示：

• 哪些文件被修改了
• 哪些文件是新添加的
• 哪些文件被删除了

2 添加文件到暂存区

将所有修改的文件添加到Git暂存区：

# 添加所有修改的文件
git add .

或者添加特定文件：

# 只添加指定文件
git add 文件名

3 提交到本地仓库

git commit -m "feat: 完成鸿蒙跨平台工程创建与多终端运行验证"

💡 提交信息规范:

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 重构代码
• test: 测试相关

4 推送到远程仓库

# 推送到默认分支（通常是main）
git push origin main

如果使用HTTPS方式，会提示输入用户名和密码：

• 用户名: AtomGit账号
• 密码: 访问令牌

---

常用Git命令速查

命令	作用
git status	查看当前状态
git add .	添加所有修改到暂存区
git add 文件名	添加指定文件到暂存区
git commit -m "说明"	提交到本地仓库
git push origin 分支名	推送到远程仓库
git pull	从远程仓库拉取最新代码
git log	查看提交历史
git branch	查看本地分支
git checkout 分支名	切换分支

---

五、验证与后续操作

5.1 可复现性验证

为了确保提交的代码是完整的且"拿来即用"，建议进行独立验证：

验证步骤：

1. 新建一个空的临时文件夹

   • 在桌面或其他位置创建一个新文件夹
   • 文件夹名称如：test-clone

2. 打开Git Bash，进入该文件夹

cd ~/Desktop/test-clone

3. 克隆远程仓库

git clone https://gitcode.com/your_username/your_project.git

4. 使用DevEco Studio打开该工程

   • 启动DevEco Studio
   • 选择 “File” -> “Open”
   • 选择克隆下来的项目文件夹

5. 直接运行项目

   • 点击DevEco Studio的运行按钮
   • 选择模拟器或真机
   • 检查是否能正常启动且无报错

如果能够正常运行，说明代码提交完整，其他人也可以正常使用。

5.2 日常开发流程

在日常开发中，推荐以下工作流程：

1. 开始工作前

   # 拉取最新代码
   git pull origin main
   

2. 开发过程中

   • 在DevEco Studio中编写代码
   • 定期保存代码

3. 提交代码

   # 查看修改
   git status
   
   # 添加修改
   git add .
   
   # 提交
   git commit -m "feat: 添加xxx功能"
   
   # 推送
   git push origin main
   

5.3 分支管理（进阶）

对于大型项目，建议使用分支进行开发：

# 创建新分支
git checkout -b feature/new-feature

# 在新分支上开发和提交
git add .
git commit -m "feat: 新功能"

# 切换回主分支
git checkout main

# 合并新分支
git merge feature/new-feature

# 推送主分支
git push origin main

# 删除已合并的分支
git branch -d feature/new-feature

---

六、安全与注意事项

6.1 常见问题及解决方案

Q1：无法创建项目

错误现象：
在DevEco Studio或其他IDE中创建项目时，提示"目录非空"或类似错误。

原因分析：
文件夹中已经存在 .git 文件夹，说明这已经是一个Git仓库，无需通过"新建项目"来重新初始化。

解决方案：

方法1：使用"从现有资源创建"项目（推荐）

对于IntelliJ IDEA或PyCharm：

1. 不要选择 “New Project”（它通常要求目录全空）
2. 选择：File -> New -> Project from Existing Sources…
3. 选择包含 .git 的那个文件夹
4. IDE会识别已有的项目结构并完成配置

对于VS Code或现代IDE：

• 直接打开目录即可
• VS Code: File -> Open Folder…，选中该文件夹
• VS Code会自动检测到 .git 并激活源码管理面板

对于JetBrains IDE：

• 点击 File -> Open…
• 选中目录，直接打开

方法2：直接打开文件夹

对于VS Code或现代IDE，直接打开该目录通常是最快捷的：

• VS Code: File -> Open Folder…
• JetBrains IDE: File -> Open…

方法3：暴力解决法（仅限必须重新新建的情况）

如果你一定要用IDE的 “New Project” 流程：

1. 先将 .git 文件夹剪切并移动到桌面或其他位置
2. 回到IDE，在原文件夹中完成 “New Project” 创建流程
3. 关闭IDE，将刚才移走的 .git 文件夹重新移动回项目根目录
4. 再次打开IDE，它会自动识别之前的Git记录

---

Q2：克隆后项目内容为空

错误现象：
执行 git clone 后，除了 .git 文件夹以外没有任何文件。

可能原因及解决方案：

原因1：分支不对

• 默认分支可能没有代码

• 解决方法：

  cd your_project
  git branch -a  # 查看所有分支
  git checkout <分支名>  # 切换到有代码的分支
  

原因2：未初始化子模块

• 如果项目包含子模块，代码可能在子模块中

• 解决方法：

  cd your_project
  git submodule update --init --recursive
  

---

Q3:：推送时身份验证失败

错误现象：
执行 git push 时提示身份验证失败。

解决方案：

1. 检查用户名和邮箱配置

   git config --global user.name
   git config --global user.email
   

2. 使用访问令牌

   • 不要使用登录密码
   • 使用访问令牌代替密码
   • 如果令牌过期，重新生成一个

3. 配置Git凭据存储（可选）

   # 设置凭据存储方式
   git config --global credential.helper store
   

   执行后，Git会记住你的凭据，下次无需重复输入

忘记访问令牌怎么办？

Q4: 忘记访问令牌怎么办？

A: 访问令牌只显示一次，需要重新生成。进入AtomGit → 设置 → 开发者设置 → 个人访问令牌 → 生成新令牌。

Q5: SSH连接失败怎么办？

A: 检查以下几点：

1. 确认公钥已正确添加到AtomGit
2. 检查私钥文件权限（Windows通常不需要）
3. 尝试使用HTTPS方式代替SSH

Q6: .gitignore不生效？

A: 执行以下命令清除缓存：

git rm -r --cached .
git add .
git commit -m "fix: 更新.gitignore"

Q7: 推送时提示"remote rejected"？

A: 可能原因：

1. 远程仓库有新提交，先执行 git pull
2. 权限不足，检查访问令牌权限是否包含repo

---

6.2 安全建议

1. 保护访问令牌

• 访问令牌就像密码，不要泄露给他人
• 不要将访问令牌提交到代码仓库
• 定期更换访问令牌

2. 不要提交敏感信息

• 不要提交密码、密钥等敏感信息
• 使用环境变量或配置文件（在.gitignore中忽略）
• 对于必要的配置信息，可以使用加密方式存储

3. 定期备份

• 重要代码建议定期备份到多个地方
• 可以同时推送到多个远程仓库

4. 使用有意义的提交信息

• 提交信息应该清晰说明本次提交的内容
• 便于后续查看和回滚

---

6.3 最佳实践

1. 频繁提交

• 小步快跑，频繁提交
• 每完成一个功能就提交一次
• 不要积累大量修改后一次性提交

2. 编写清晰的提交信息

• 使用统一的提交信息格式
• 信息要简洁明了

3. 推送前检查

• 推送前先 git status 检查状态
• 确认没有意外添加的文件
• 运行测试确保代码可运行

4. 合理使用分支

• 新功能使用新分支开发
• 开发完成后再合并到主分支
• 保持主分支始终可运行

5. 定期更新代码

• 每天开始工作前先 git pull
• 避免出现严重的代码冲突

---

七、总结

通过本教程，你已经学会了：

🌸 安装和配置Git开发环境
🌸 注册AtomGit账号并创建公开仓库
🌸 配置SSH密钥实现免密码提交
🌸 使用DevEco Studio创建鸿蒙跨平台项目
🌸 配置.gitignore文件
🌸 生成和使用访问令牌
🌸 使用Git提交和推送代码
🌸 解决常见问题和注意事项

下一步学习建议

1. 深入学习Git

   • 学习Git分支管理
   • 了解Git冲突解决
   • 掌握Git回滚和撤销操作

2. 学习HarmonyOS开发

   • 深入学习ArkTS语言
   • 学习HarmonyOS UI框架
   • 掌握多设备适配

3. 参与开源社区

   • 加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
   • 贡献代码到开源项目
   • 与其他开发者交流学习

---

八、参考资料

• Git官方文档
• AtomGit使用文档
• DevEco Studio开发指南
• HarmonyOS开发文档

---

欢迎加入开源鸿蒙跨平台社区: https://openharmonycrossplatform.csdn.net