企业官网建设流程全解析

最近一直在折腾OpenHarmony的跨平台开发，从工程创建到代码托管这条路走得不算特别顺，但踩过坑之后算是把完整的链路摸透了。这篇实战记录想围绕几个核心关键词展开：OpenHarmony、跨平台开发、工程创建、AtomGit平台自建公开仓库。很多人刚开始接触鸿蒙生态时，最头疼的往往不是业务代码本身，而是“工程怎么建、环境怎么配、代码放到哪里托管、别人怎么访问我的开源项目”这些基建问题。这篇文章就是把这些基建问题一次性讲清楚，从零开始搭建一个可运行的OpenHarmony工程，再把源码推送到AtomGit平台的公开仓库，整个过程都会有实际操作的细节和避坑经验。

如果你是刚接触OpenHarmony开发，或者希望把项目源码托管到一个可公开访问的代码仓库，这篇内容应该能帮你少走不少弯路。我会把整个项目拆成环境准备、工程创建、平台建仓、代码推送四个阶段来讲述，每一步都会解释为什么这么做，而不只是给你一堆命令。

1. 项目整体思路与关键决策解析

1.1 为什么选择OpenHarmony做跨平台开发

OpenHarmony并不是传统意义上的“跨平台开发框架”，它的跨平台特性更多体现在跨设备、跨形态上。同一个工程可以通过不同的工程配置和SDK支持，编译运行在手机、平板、智能座舱、智能家居等多种设备上。这种从系统层面统一生态的做法，和“一次编写、多端运行”的开发体验不太一样，它是在底层就把设备差异抹平了。

我在做这个项目时，最看重的就是这一点。如果用传统的安卓开发，你需要针对不同屏幕尺寸做大量适配；而OpenHarmony在应用层提供了相对统一的UI语法和状态管理机制，代码可以在不同形态设备上复用，对中小型团队来说，降低了多端维护的成本。

另外，OpenHarmony的生态工具链现在已经比较完整，工程脚手架、模拟器、SDK管理、调试工具都是一条龙的。整个开发体验其实已经非常接近主流移动平台，这对从其他平台转过来的开发者来说，学习曲线不算陡。

1.2 为什么选择AtomGit作为代码托管平台

代码托管平台的选择其实会直接影响开源项目的传播效率。项目原计划托管到常用的海外平台，但在实际测试中发现，某些网络环境下访问和推送代码的速度并不稳定，于是就把目光转向了AtomGit。

AtomGit是面向开发者的代码托管服务平台，它有几个很实在的优点。

第一是访问速度快，对国内开发者非常友好，推送和拉取代码的体验都很顺，不需要额外处理网络问题。第二是支持自建公开仓库，而且免费用户就能创建足够数量的公开仓库，这对开源项目和个人学习项目来说非常重要。第三是它对Git协议是完全兼容的，你在本地用标准的git命令操作就行，不需要学习一套新的工具链。第四是平台内置了问题追踪、分支管理和代码检视的基础能力，虽然不像某些企业级平台那么复杂，但对个人项目和小团队协作已经完全够用了。

有个细节我在一开始就确认过：AtomGit支持通过SSH协议推送代码，这意味着我可以配置一次密钥之后，后续推送都不需要反复输入密码，整个流程非常顺滑。

1.3 整体流程设计与阶段划分

整个项目我划分成了四个阶段，每个阶段都有独立的产出物，这样在排查问题时能快速定位到具体环节：

• 阶段一：环境准备。安装必要的开发工具、配置SDK、准备模拟器。
• 阶段二：工程创建。用工程向导生成一个可运行的基础项目，理解目录结构。
• 阶段三：平台建仓。在AtomGit上创建公开仓库，配置SSH密钥。
• 阶段四：代码推送。将本地工程与远程仓库关联，完成首次推送。

这个顺序其实隐藏了依赖关系：前两个阶段是基础，后两个阶段是发布链路。如果把建仓放到环境准备之前，你会发现自己根本没有代码可以推；如果把推送放到最后，你会发现没法和别人共享代码。所以这个顺序不是随便排的，而是按照项目推进的实际依赖来设计的。

2. 开发环境准备：工具链搭建全流程

2.1 安装集成开发环境

OpenHarmony应用开发首选的IDE是扩展工具，不过我更推荐直接用官方提供的集成开发环境，因为它对OpenHarmony工程的支持是开箱即用的，省去了很多插件配置的麻烦。

安装过程本身比较简单，但有几个细节值得注意：

• 安装路径建议避开系统盘的系统目录，因为我遇到过因为权限不足导致构建工具无法生成临时文件的情况。
• 安装完成后首次启动，IDE会引导你配置开发环境的路径，这个路径建议设置在一个独立的目录，方便后续管理。
• 如果电脑上之前装过其他版本的SDK，最好在新的开发环境里重新指定路径，避免版本冲突。

2.2 SDK配置与依赖管理

打开IDE的SDK管理器，选择OpenHarmony SDK版本，等待它自动下载。这里有个经验：SDK下载过程可能需要一段时间，尤其是在网络环境一般的情况下，建议预留半小时以上。

SDK安装完成后，还需要确认几个关键配置项：

• Node.js环境。新版开发工具链依赖Node.js来执行构建脚本，如果没装，后续编译会直接报错。
• ohpm依赖管理。这个工具负责管理OpenHarmony的依赖包，类似于其他平台的包管理工具。第一次创建工程时，IDE会自动调用它来拉取基础依赖。
• hvigor构建工具。这是OpenHarmony的构建引擎，负责编译打包。IDE通常会自动处理，但如果你手动配置过环境变量，要注意版本匹配。

我踩过的一个坑是：配置了多个版本的Node.js环境，导致ohpm在检索依赖时指向了错误的执行路径，最终构建报错提示版本不匹配。解决办法是把环境变量统一指向同一个版本的Node.js，然后重启IDE。

2.3 模拟器准备与运行环境验证

在开始写代码之前，我建议先创建一个模拟器，这样可以在后续步骤中随时验证运行效果。

创建模拟器的路径比较简单：打开设备管理面板，选择创建一个新设备，然后选择对应的设备类型和系统镜像，等待镜像下载完成即可。每一步都有界面引导，按提示操作就能完成。

需要注意，模拟器镜像的体积通常不小，动辄几个GB，所以磁盘空间要预留充足。我第一次创建模拟器时，因为当时项目目录所在盘符空间不够，模拟器启动后一直白屏，后来才发现是数据盘满了。

模拟器启动成功后，建议先用它随便跑一个内置的示例页面，确认整个工具链是通畅的，再进入工程创建阶段。

3. 工程创建：从向导到首屏渲染

3.1 新建工程的向导参数选择

打开IDE后，选择“新建工程”，会出现工程向导页面。这里有几个关键参数需要仔细选：

• 工程类型。选择“Application”还是“AtomicService”，取决于你的目标。如果只是做普通应用，选Application即可。模板方面，我建议选“Empty Ability”，轻量干净，没有任何多余的示例代码。
• 兼容版本。这里会选择最低支持的OpenHarmony版本。建议选一个相对主流的版本区间，既不要太新（可能没有足够的设备覆盖），也不要太旧（很多新API用不了）。
• 工程名称与包名。包名需要符合反向域名的命名规范，比如com.example.myproject这种格式。包名一旦确定，后续大部分配置都会围绕它来生成，所以最好提前想清楚。

工程创建完成后，IDE会自动初始化工程结构，并同步下载依赖。这一步结束后，你的项目其实已经具备编译能力了。

3.2 工程目录结构解读

强烈建议在动手改代码之前，先把OpenHarmony的工程目录结构读懂。它不是随便分层的，每一层都有明确的职责：

项目名称/ ├── AppScope/ │ ├── app.json5 # 应用级配置文件 │ └── resources/ # 公共资源目录 ├── entry/ │ ├── src/main/ │ │ ├── ets/ # 源码目录（ArkTS代码） │ │ ├── resources/ # 模块资源目录 │ │ └── module.json5 # 模块配置文件 │ ├── build-profile.json5 # 构建配置 │ ├── hvigorfile.ts # 构建脚本 │ └── oh-package.json5 # 依赖配置 ├── build-profile.json5 # 工程级构建配置 ├── hvigorfile.ts # 工程级构建脚本 ├── oh-package.json5 # 工程级依赖配置 └── .gitignore # Git忽略规则

简单理解，AppScope是应用层面，entry是入口模块层面。大多数情况下，你需要在entry/src/main/ets下写页面代码，在entry/src/main/resources下放图片、字符串等资源。这样分层的好处是清晰，但如果是第一次接触，很容易在找文件的时候迷路。

3.3 修改基础配置与首次运行

创建完空工程后，我先改了两个地方：

一是修改应用显示名称。在entry/src/main/resources/base目录下的字符串资源文件里，把默认的module_desc和app_name改成自己的项目名。这个改动会影响桌面显示的应用名，别看它小，但经常有开发者忘记改，发布后桌面显示的是默认名，非常不专业。

二是确认module.json5里的配置。这里声明了模块的入口Ability、权限声明和设备类型支持。比如你的应用只需要支持手机和平板，设备类型列表里就只保留这两个。如果不小心勾选了不支持的类型，模拟器可能无法安装运行。

改完之后，我直接点运行按钮，把工程推送到刚才创建的模拟器上。第一次编译会比较慢，因为要生成中间产物，耐心等就好。看到模拟器上弹出应用页面那一刻，说明整个环境链路已经通了。

3.4 签名设置的关键细节

很多新手在这个环节会卡住。OpenHarmony应用在调试和发布时都需要签名，IDE在调试模式会自动帮你生成一个调试证书，但你需要在工程配置里启用自动签名。

具体操作是在IDE的签名配置界面里勾选自动生成签名，并配置对应的证书文件。如果你跳过这一步直接运行，可能会遇到安装应用时签名校验不通过的错误。我当时第一次运行时，弹出的错误提示指向了应用安装失败，排查了很长时间才发现是签名没有开启自动生成。

在后续操作中，这个自动签名配置也会参与构建，所以在做代码推送之前，务必确认签名配置没有问题。如果你后续需要发布正式包，还要去注册对应的发布证书，这一步就涉及更复杂的证书管理了，我这里先不做展开。

4. AtomGit平台自建公开仓库：完整实操记录

4.1 平台能力与仓库类型选择

在AtomGit平台上创建仓库，首先要明确仓库类型。平台通常提供公开仓库和私有仓库两种模式：

• 公开仓库：所有互联网用户都能看到你的代码，适合开源项目、学习笔记、Demo源码。
• 私有仓库：仅你自己或指定成员可见，适合商业项目、未完成的作品。

因为我们项目规划是开源共享，所以选择公开仓库。这里有一个容易被忽略的点：公开仓库一旦创建，仓库名几乎是不可更改访问路径的，因为在公开状态下，可能会有外部开发者引用你的仓库地址。所以仓库名称要想好再动手。

仓库名称我建议使用“项目名”或“项目名-平台”的格式。比如你做一个鸿蒙计算器，仓库名可以是oh-calculator或harmony-calculator。尽量用英文和字母，避免中文名在URL传递时出现编码问题。

4.2 SSH密钥生成与账号绑定

在推送代码之前，一定要配置SSH密钥。虽然HTTPS协议也能推送，但每次都要输入账号密码，如果开启了双因子认证，你还需要额外生成访问令牌，那体验会非常痛苦。SSH密钥一旦配置好，后续的推送和拉取都是无缝的。

生成密钥的命令在所有主流操作系统上都通用：

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

执行后会让你确认保存路径和设置口令，我这里建议直接回车使用默认路径（~/.ssh/id_rsa），口令也留空。如果设置了口令，后续每次推送都可能要求输入，在自动化流程里非常烦人。

然后查看公钥内容：

cat ~/.ssh/id_rsa.pub

接下来，复制输出的整段内容，到AtomGit平台的SSH公钥设置页面，粘贴保存。有些系统上公钥文件和Windows的路径不太一样，但只要你用的是标准生成命令，公钥文件一定在用户主目录下的.ssh目录里。

4.3 创建公开仓库的操作细节

在AtomGit的仓库管理页面，选择“新建仓库”，然后填写关键信息：

• 仓库名称。顶格填写，注意不要和已有仓库重名。
• 仓库描述。这一句话会展示在仓库首页，建议写清楚“这是什么项目、用什么技术栈开发、主要解决什么问题”。好的描述对提升项目曝光有很大帮助。
• 可见性。选择“公开”。
• README初始化。建议勾选自动生成README文件。这个文件是仓库的门面，即使初始内容比较简单，也比空仓库看起来可信得多。

还有一个细节是许可证选择。如果项目代码你希望别人随便用，可以选择MIT；如果希望更强调版权保护，可以选择Apache 2.0。默认情况下，如果不太确定，可以先不选，后续补上也是可以的，但早期选择好对开源项目的规范化很有意义。

创建完成后，仓库会生成一个唯一的访问地址，包括HTTPS地址和SSH地址。我们后续推送主要用SSH地址。

4.4 本地初始化与代码推送

现在到了核心步骤：把本地工程推送到远程公开仓库。

在项目根目录打开终端，按下面的流程操作：

# 初始化本地仓库 git init # 查看当前文件状态 git status

初始化后有一个重要工作：检查.gitignore文件。OpenHarmony工程在创建时已经自动生成了.gitignore，这个文件会过滤掉build目录、.hvigor目录、.idea目录等构建产物。你千万不要把构建产物也推到公开仓库里，否则仓库体积会迅速膨胀，而且别人拉下来根本不是源码。

确认忽略规则合理后，添加所有文件并提交：

git add . git commit -m "Initial commit for OpenHarmony project"

把远程仓库地址加入配置：

git remote add origin <你的AtomGit仓库SSH地址>

把本地分支改为main并推送：

git branch -M main git push -u origin main

如果SSH密钥配置正确，这时候不会要求输入任何密码，首次推送会有点慢，因为要传输所有文件。推送完成后，在AtomGit仓库页面刷新，就能看到完整的源码了。

有个小细节：有些平台的默认分支是master，有些是main，在推送前用git branch -M main强制改成main，可以避免后续出现“默认分支名不一致”的混淆问题。

4.5 仓库维护与开源规范建议

仓库创建并推送成功后，工作其实还没有完全结束。

开源项目要能真正被别人发现和使用，有三个细节值得做：

第一个是完善README.md。不要只放一句话，建议把项目的功能截图、运行环境要求、编译步骤、使用说明都放进去。我们在实际开发中为了让项目复现更顺利，还专门加了一个“从零运行”章节，把环境准备和运行命令一步步列出来，极大降低了使用者的上手成本。

第二个是补充许可证。如果你新建仓库时没有选许可证，建议现在补一个。没有许可证的代码在法律上等于保留所有权利，别人使用时会有顾虑。而声明了MIT或Apache 2.0之后，能大大降低使用者的心理门槛。

第三个是标签管理。顺手给仓库打个版本标签，比如v1.0.0，这样别人可以下载到固定版本的归档包，不必总是从主分支上拉取未稳定的代码。用git打标签非常简单：

git tag v1.0.0 git push origin v1.0.0

这些细节都是开源协作中非常基础但又容易被忽视的部分，做得好，项目会更像一个规范的开源项目，而不是个人备份。

5. 常见问题与排查技巧实录

5.1 环境与编译类问题

其中API版本不匹配是最容易误导人的一个问题。有时候你在官方文档里看到一段示例代码，但本地的SDK还没更新到那个版本，编译就会报错。这种情况我建议直接看错误日志，它会明确告诉你期望的最低API版本是多少，对照日志调整即可。

5.2 Git与仓库类问题

这里要特别解释一下.gitignore不生效的问题。很多人创建工程后直接git add .，此时编译生成的大批量构建文件已经被纳入版本管理了；后面再补写.gitignore时，这些文件依然会被跟踪，因为你只是忽略了“未跟踪的文件”，对已经跟踪的文件不起作用。正确做法是重置缓存：

git rm -r --cached . git add . git commit -m "fix: update gitignore rules"

这样才会真正让忽略规则生效。

5.3 容易被忽略的细节

除了上面这些问题之外，还有几个实践细节值得记住：

• 公开仓库的提交信息要用规范格式。既然仓库是公开的，提交信息就是你对外的门面。建议用feat:、fix:、docs:这类规范的提交前缀，别人在看提交历史时一目了然。
• 发现提交了敏感信息怎么办。不要在公开仓库中提交任何密钥、证书文件、私密配置。万一误提了，修改文件再提交是没用的，因为历史提交中仍然有敏感信息。这时候需要重写历史或者更换密钥，在大规模公开仓库中这是一个比较严重的隐患，务必要避免。
• 工程同步备份。推送到各个平台之后，可以定期用“拉取到新目录”的方式验证仓库是否完整。我习惯每完成一个功能模块就做一次git clone到临时目录，确认Clone下来的工程能正常编译。这样能观察到从纯远程状态还原工程是否有遗漏。

6. 我的一些实战体会

这个项目虽然看起来只是“建工程、推送代码”两个动作，但实际操作下来，链条上的每个环节都有各自的坑需要填。

我个人觉得，OpenHarmony的工程体系和代码托管平台的配合已经相当成熟了，只要环境配置正确，整个流程是非常顺的，大部分卡壳都发生在环境不一致和忽略规则缺失上。如果你正在做类似的鸿蒙项目，我的建议是先把工程创建和签名这类基本功练扎实，再去研究复杂的业务模块。地基打得稳，后面跑起来才不费劲。

最后再分享一个小技巧：当你在新建OpenHarmony工程时，如果你确定的包名和项目名以后会作为开源项目发布，那么在写工程描述的时候就正式一点。这虽然是无形的细节，但它会在别人搜索和判断是否使用你的代码时，起到超乎想象的作用。