项目标题里带着"2025 最新"和"带图展示"两个标签，说明这是一篇典型的入门环境搭建文。但真正动手装过 HarmonyOS 6 的 DevEco Studio 的人都知道，卡住新手的从来不是点"下一步"，而是那些向导页里没人解释的勾选项、装完之后第一次同步失败、模拟器镜像下到一半没反应、真机连上却提示签名错误。这篇我不打算堆截图，而是把每个界面上你该盯住的字段、每个弹窗背后的判断逻辑写清楚，图片会过期，判断方法不会。适合三类人看：完全没接触过 HarmonyOS 应用开发、想先把环境跑通的新手；从旧版本 IDE 迁过来、想搞清楚工具链变化的开发者；以及带新人时懒得一遍遍重复讲环境配置的老手。全文围绕 DevEco Studio 的下载、安装、SDK 组件配置、模拟器与真机调试这几件事展开，穿插我在多台机器上踩过的坑，能直接照抄的部分我会给到具体路径和参数。

1. 装之前先算账：DevEco Studio 6 到底吃多少资源

很多人拿到安装包的第一个反应是"这么大？"，第二个反应是"装完怎么C盘红了"。环境搭建的第一步不是下载，而是先确认你的机器和磁盘能不能扛住整套工具链，否则后面所有报错都会被误判成"软件有问题"。

1.1 硬件与系统门槛逐项对照

官方给出的最低配置通常很保守，实际体验差距很大。下面这张表是我按"能用"和"好用"两档整理的，你可以直接对照自己的机器：

有两点值得单独说。第一，内存这一项不要迷信"能开就行"。DevEco Studio 本身是基于 IntelliJ 平台的，它的代码索引、语法分析、预览器渲染都是内存大户，8 GB 机器上你会看到 IDE 一直显示"正在索引"，输代码时补全延迟半秒以上，这种体验很快就会让人放弃。第二，如果你是 Apple Silicon 的 Mac，务必确认下载的是 ARM 架构的安装包，跑 x86 版本要靠转译层，启动时间和编译速度都会明显退化，这一点在第 4 章会细说。

1.2 安装包体积背后的账：为什么预留空间不是 10G 而是 60G

安装包本身通常只有 1 GB 到 2 GB，但装完之后占用会翻好几倍，原因在于 DevEco Studio 不是一个单体 IDE，它是"IDE + SDK + 工具链 + 模拟器镜像"的打包体。我拆解一下装完之后的体积构成，你就明白空间去哪了：

• IDE 主体：解压后约 2 GB 到 3 GB，包含 IntelliJ 平台本体和 DevEco 的插件层。
• SDK 与 API 版本：每个 API 版本一套，包含 ArkTS 声明文件、系统能力接口描述、资源包，单个版本 1 GB 到 2 GB。新手往往会一口气勾选三四个版本，这是磁盘爆炸的头号原因。
• 构建工具链：hvigor、ohpm 的本地缓存，第一次同步工程时会下载一堆依赖，缓存目录通常落在用户目录下，几十万个文件、几 GB 空间很正常。
• 模拟器系统镜像：单个手机镜像 2 GB 到 4 GB，平板和二合一设备更大，而且镜像一旦创建，删除要走专门的设备管理器，直接删文件夹容易留下脏数据。
• 构建产物与索引：每个工程的 build 目录、.hvigor、.idea 索引缓存，单工程 500 MB 起步。

所以我的建议很直接：把 IDE 和 SDK 装在非系统盘，并且路径里不要有任何中文和空格（第 6 章会解释为什么这个是硬性要求）。缓存目录默认在用户目录，如果系统盘吃紧，可以通过环境变量把缓存根目录挪到大盘上，这一点在第 7 章给具体做法。

提示：安装前先清一次磁盘，把"可用空间"做到 100 GB 以上。装到一半空间不足导致的损坏，比一开始就空间不足更难排查，因为报错会出现在完全不相关的地方。

2. 下载环节的取舍：版本、渠道与校验

下载这一步看起来最没有技术含量，但它决定了你后面两小时的体验。我见过太多人因为下错架构、下错版本，在签名报错和模拟器黑屏上反复折腾，最后发现源头就是安装包本身不对。

2.1 版本号怎么读：API 版本与 IDE 版本的对应关系

DevEco Studio 的版本和 HarmonyOS 的 API 版本是两套编号，新手最容易在这里绕晕。IDE 大版本（比如 6.x）决定的是工具本身的界面和功能；API 版本（也叫 SDK 版本、compatibleSdkVersion 里的数字）决定的是你的应用能调用哪些系统能力、能在哪些设备上运行。

实际选版本的策略是这样的：如果你只是学习、跑通 Demo，选最新的稳定版 IDE + 一个最新的稳定 API 版本就够了，多装无益；如果你要接手一个已有工程，那就要先看那个工程的构建配置文件里写的 compatibleSdkVersion 是多少，然后倒推需要装哪个 API 版本——装高了会提示 API 不匹配，装低了会有一堆接口找不到。工程里这两个字段通常写在 build-profile.json5 的 products 节点下，形如：

{ "app": { "products": [ { "name": "default", "signingConfig": "default", "compatibleSdkVersion": "6.0.0(20)", "runtimeOS": "HarmonyOS" } ] } }

看到compatibleSdkVersion这一行，你就知道该装哪个版本了。这里的括号数字就是 API 版本号，前面的 6.0.0 是系统版本。这个对应关系记住一次就够用：IDE 负责"怎么编译"，API 版本负责"编译出什么"。

2.2 下载完成后先别双击：校验与路径的坑

安装包从浏览器下载下来之后，先做两件事再双击。

第一件是核对文件大小和完整性。下载中断在浏览器里有时候不会明确报错，尤其是网速波动大的时候，文件看起来在那儿，实际是残缺的。Windows 上右键看属性里的字节数，和下载页显示的大小对一遍；macOS 上可以用shasum -a 256 文件名算一次摘要，和页面上提供的校验值比对。这一步花三十秒，能省掉后面"安装到 60% 突然失败"的半小时。

第二件是决定把安装包放在哪。不要把安装包放在桌面或者下载目录里直接运行，尤其是路径里有中文的时候。我习惯的做法是在大盘根目录下建一个纯英文目录，比如D:\dev-tools\或者/Users/xxx/dev-tools/，把安装包、解压后的 SDK、工程代码都放在这个目录树下面，路径短、无空格、无中文，后面所有工具链相关的怪问题都能少一半。

# macOS 上快速校验，和下载页的 SHA256 对比 shasum -a 256 ~/dev-tools/deveco-studio-mac-arm64.dmg

注意：下载渠道只走官方开发者网站。第三方网盘、论坛附件里的"绿色版""免安装版"看起来省事，但工具链完整性无法保证，签名证书和 SDK 组件一旦被替换过，后面出现的构建错误会非常难定位，而且没有任何排查价值。

3. Windows 侧安装实录：从向导第一步到首次启动

下面这一节按顺序走一遍 Windows 上的安装流程。不同小版本之间向导页的措辞会略有差异，但字段含义是稳定的，你按语义对应即可。

3.1 安装向导里那几个勾选项分别意味着什么

双击 exe 之后，前两页是许可协议和安装路径，真正需要动脑的是组件选择页。这一页通常有这么几项：

• DevEco Studio 主程序：必选，没得商量。
• SDK（软件开发工具包）：可选但强烈建议在安装时就选上。如果这里不勾，装完之后要在设置里手动指定 SDK 路径，多一步而且容易指错目录。
• 命令行工具：包含 hdc、ohpm 等。建议勾选，后面真机调试、安装 HAP、看设备日志都要用它。
• 桌面快捷方式 / 关联文件类型：按个人习惯，关联.ets、.json5这类文件类型能省不少双击打开的时间。

安装路径这里再强调一次：纯英文、无空格、非系统盘。像D:\Program Files\DevEco Studio这种带空格的路径，在某些构建脚本里会被当成两个参数传进去，症状是编译到一半报"找不到文件"，但文件明明就在那儿。我一般直接用D:\dev-tools\deveco-studio。

安装过程通常五到十分钟，取决于磁盘速度。装完后向导会问要不要立即启动，我的建议是先不启动，先去把下面这件事做了：确认安装目录下的bin子目录里有devecostudio64.exe，有就说明主程序完整；再确认 SDK 目录是否存在。这两项确认完再启动，能避免"启动后一片空白"这种无头绪的状况。

3.2 SDK 组件选择：全量装和按需装的代价

首次启动时 IDE 会引导你配置 SDK，这是整个安装流程里最需要判断力的一步。SDK 组件列表通常按 API 版本分组，每组下面有若干条目：ArkTS 语言支持、系统能力接口、预览器运行时、模拟器镜像等。

常见的两种做法和它们的代价：

我倾向第二种。原因很实际：新版本刚出来的时候，某些三方库还没来得及适配，你偶尔需要退回上一个版本验证问题是库的问题还是系统的问题。全量装则纯属浪费，索引范围变大之后，IDE 的搜索和跳转会明显变慢。

另外有个细节：SDK 的存放位置不要和 IDE 装在同一层目录下混着放，单独开一个sdk目录。后面如果换 IDE 版本，SDK 目录可以复用，不用重新下几个 G。

3.3 首次启动的向导页：Node、ohpm、hvigor 三件套

现代前端和移动端的 IDE 都在往"自带运行时"的方向走，DevEco Studio 也一样。首次启动时你会看到一个环境初始化页面，里面涉及三个组件：

• Node.js：ArkTS 的编译和一部分构建脚本跑在 Node 上。IDE 通常自带一份，也可以指向你系统里已装的版本。这里有个坑：如果你的系统 Node 版本太新或者太旧，和 IDE 内置的 hvigor 版本不匹配，会出现"同步成功但编译报语法错误"的诡异情况。我的做法是直接用 IDE 自带的，不去指向系统 Node，等稳定了再说。
• ohpm：包管理器，类比 npm，但专用于 HarmonyOS 的包仓库。它会在用户目录下建一个.ohpm缓存目录，并且有一次性的仓库地址配置。
• hvigor：构建工具，类比 Gradle 在 Android 生态里的角色。它负责把 ArkTS 编译成字节码、打包成 HAP/APP、执行签名和安装。

这一页如果显示某个组件"未安装"或者版本号是灰的，点一下组件右侧的安装/修复按钮，让它自己下完。三个组件都变绿之后再进入主界面。我见过有人跳过这一步直接建工程，结果第一次同步就报hvigor not found，然后又回头折腾环境，反而更慢。

初始化完成后主界面会打开，此时先别急着建工程，做一件事：打开设置，找到构建工具相关的配置项，确认 hvigor 的路径指向的是 IDE 安装目录下的那一份，而不是空值。这个确认动作十秒钟，能挡掉一个高频报错。

4. macOS 侧安装差异：架构与权限那些事

macOS 上的流程整体更短，但有两个 Windows 上不存在的坑：架构选择和系统安全拦截。

4.1 Apple Silicon 与 Intel 的包是否通用

下载页一般会同时提供两种架构的安装包，文件名里带arm64的和带x64（或intel）的。判断自己的机器该用哪个：

# 一条命令看清架构 uname -m # 输出 arm64 就是 Apple Silicon，输出 x86_64 就是 Intel

为什么不建议在 Apple Silicon 上装 x64 版本？因为要靠转译层执行，IDE 的启动时间会从几秒变成十几秒，索引和编译也慢一截，更麻烦的是模拟器镜像的加载路径在转译环境下偶尔会出问题。这不是"不能用"，而是"没必要忍受"。

dmg 安装就是把图标拖进 Applications 目录，这一步没什么可讲的。装完之后从启动台打开即可，但第一次打开大概率会被系统拦下来。

4.2 首次打开被拦下时的正确处理方式

被拦下时的提示大致是"无法验证开发者"，处理方式是打开"系统设置 - 隐私与安全性"，在页面下方找到关于刚才那个应用的提示，点"仍要打开"，然后重新启动一次即可。注意这个按钮只在拦截发生之后的一段时间内出现，所以顺序是：先尝试打开一次 → 被拦 → 去设置里放行 → 再打开。

不要用网上那种"全局关闭安全校验"的做法，那等于为了装一个 IDE 把整台机器的防护都降级了，性价比极低。也不要反复右键打开碰运气，新版系统上这个老技巧基本失效了。

还有一个小细节：macOS 上 SDK 和缓存的默认位置在用户目录下的隐藏文件夹里（以点开头），用 Finder 找不到，要么用Cmd + Shift + .显示隐藏文件，要么直接在终端里cd进去。如果你想把它们挪到大容量外置盘或者非系统分区，可以用环境变量指定，第 7 章会写。

5. 跑通第一个工程：从模板到模拟器出画面

环境装完不代表打通了，真正的验收标准是"代码能编译、应用能在模拟器或真机上跑起来、改一行代码能看到变化"。这三个都过了，环境才算真正可用。

5.1 建工程时那几个字段的实际影响

新建工程的向导页字段不多，但每个都有后果，我逐个说：

Bundle name（包名）。这是应用的唯一标识，格式是反向域名加应用名，比如com.example.demo。它一旦确定，后面要改就得连带改签名材料和配置，非常麻烦。而且它必须是纯英文、点号分隔、不能有下划线开头的段。我的建议是建工程时就想清楚命名，别用默认的com.example.myapplication就往下走。

Module name（模块名）。一个工程可以有多个模块，最基础的是 entry 模块（应用入口）。模块名会作为目录名出现在工程结构里，也会写进配置文件的module.name字段。用英文小写，别用驼峰，避免某些脚本处理时大小写不一致。

Compatible SDK（兼容 SDK 版本）。这个字段直接决定你能用哪些接口、应用能装在什么系统上。选的时候IDE会给出可选列表，这些列表项对应的就是你实际装了的 SDK 版本。如果列表是空的，说明 SDK 没装好，回第 3.2 节补装。

模板类型（Template）。新手直接选"Empty Ability"这种空工程模板就行，它会帮你生成一个带页面、带路由、带资源目录的最小可运行结构。别一上来就选带复杂功能的模板，那些模板里的示例代码会成为你排查问题的干扰项。

建完之后等 IDE 自动同步依赖。第一次同步会下载 hvigor 插件和一堆积木包，慢是正常的，判断标准是底部的进度条在动、日志在刷。如果三分钟没有任何输出，那才是卡住了，处理方式见第 6 章。

工程建好之后先认识两个文件，后面调错全靠它们：

工程根目录/ ├── build-profile.json5 # 构建配置：SDK 版本、签名、目标设备 ├── hvigorfile.ts # 构建脚本入口，类似 Gradle 的 build.gradle ├── oh-package.json5 # 依赖声明，类比 package.json └── entry/ # 主模块 ├── src/main/ets/ # ArkTS 源码 ├── src/main/resources/ # 资源文件 └── src/main/module.json5 # 模块配置：入口 Ability、权限声明

5.2 模拟器创建：镜像下载与资源分配

点工具栏的设备管理入口，会打开设备管理器。第一次进去是空的，需要先下载系统镜像，再基于镜像创建设备。这里有几件事值得提前知道：

镜像下载是整条安装链路上最慢的一步，单个镜像通常 2 GB 以上，而且下载器在弱网下的重试机制不太友好——断了之后有时候要重新开始。我的经验是找一段网络稳定的时间一次下完，别在下载过程中反复切网络环境。镜像下完之后会有一个校验过程，别在这个阶段关掉 IDE。

创建模拟器时的资源分配有两个参数需要手动调：内存和存储。默认给的内存偏小，跑复杂界面会卡。我一般把手机模拟器给到 4 GB 内存、8 GB 存储，这个配置足以跑通绝大多数示例。另外，模拟器会占用宿主机的 CPU 虚拟化能力，如果你的机器在 BIOS 里没开虚拟化，模拟器会创建成功但启动不起来，症状是卡在开机画面。这一点在 Linux 和 Windows 上都成立，第 6 章排查表里会再提。

设备类型的选择上，新手从手机型号开始就好。平板和二合一设备的界面适配差异较大，等你熟悉了断点、路由、布局之后再去碰。

模拟器起来之后，点 IDE 的运行按钮，选择刚建好的模拟器作为目标设备。第一次运行会走完整的编译、签名、安装流程，耗时比较长；后面改代码再运行就是增量的，快很多。看到默认页面渲染出来，说明整条链路通了。

5.3 真机调试：签名配置的最小闭环

模拟器能跑之后，很多人会立刻想上真机，然后卡在签名上。签名这块的逻辑其实不复杂，我把它拆成三步：

第一步，让设备能被识别。在设备上打开开发者模式和 USB 调试，用数据线连上电脑，然后在终端里执行hdc list targets。这条命令是 HarmonyOS 设备连接工具的查询指令，能列出已连接的设备。如果输出是空的，说明驱动或者授权没到位，先解决这一步再谈签名。

第二步，准备签名材料。签名需要几样东西：密钥库文件（.p12）、证书请求文件（.csr）、证书文件（.cer）、以及描述文件（.p7b）。如果只是自己调试用，IDE 里有自动签名的入口，登录开发者账号后由工具链自动生成和管理这套材料。如果暂时不方便登录，那就得手工准备，把这几样文件放到一个固定目录，在工程的签名配置里逐个指向。

第三步，把签名配置写进工程。签名配置写在build-profile.json5的signingConfigs节点里，大致结构如下（路径换成你自己的）：

{ "app": { "signingConfigs": [ { "name": "default", "type": "HarmonyOS", "material": { "certpath": "./signature/demo.cer", "storePassword": "0000", "keyAlias": "demo", "keyPassword": "0000", "profile": "./signature/demo.p7b", "signAlg": "SHA256withECDSA", "storeFile": "./signature/demo.p12" } } ] } }

密码这类敏感信息不要直接明文提交到代码仓库，正式的工程里应该走环境变量或者本地的未跟踪配置文件。调试阶段图省事直接写明文，但心里要有数，别把这段配置连同密码一起推到公共仓库里。

宽带连好、签名配好之后，运行目标切到真机，点运行。安装成功的标志是设备上出现了应用图标，而且能点开。到了这一步，环境彻底打通，可以开始写业务代码了。

6. 装完之后最容易卡住的六个问题与排查链路

这一节全部是实战里遇到的真实卡点。我不直接给答案，而是按排查顺序写，因为下次你遇到的报错文案可能不完全一样，但排查链路是通用的。

6.1 中文路径与空格路径引发的连锁反应

症状：编译到某一阶段突然报找不到文件，日志里的路径看着是对的，但文件夹里确实没那个文件；或者报某个脚本执行失败，看不出具体原因。

排查顺序：先看安装目录是不是含中文或空格 → 再看工程所在路径 → 再看 SDK 路径 → 最后看用户目录（有些系统用户名本身就是中文）。

原理：构建工具链里有一批脚本是用命令行的方式调用编译器的，路径里带空格会被 shell 拆成两个参数，带中文会在编码转换环节出问题。这类错误的特点是"看起来哪儿都没错"，因为 IDE 的路径显示做了一次规范化，你看不出问题，但底层的调用已经错了。

修复：把所有相关目录改成纯英文无空格。安装路径、工程路径、SDK 路径这三处都检查一遍。改完之后清一次构建缓存再重新同步。这是我认为最应该前置解决的一类问题——装之前改一次路径，比装之后折腾半天划算得多。

6.2 思维要换：hvigor 与 ohpm 的报错怎么读

从 Android 生态过来的人，第一反应是找 Gradle 的对应物。hvigor 就是那个对应物，但报错格式和调试思路不一样。hvigor 的报错通常会明确指出是哪个任务（task）失败，比如:entry:default@CompileArkTS，这个冒号路径就告诉你失败发生在 entry 模块的 ArkTS 编译阶段。

ohpm 的报错则集中在依赖解析上，典型文案是找不到某个包或者版本冲突。这时候看oh-package.json5里的依赖声明，以及用户目录下.ohpm缓存目录的日志。

我总结了一个粗线条的判断规则，能快速定位层级：

这个表不能替代读日志，但能让你在三秒内决定往哪个方向翻。新手最常见的误区是看到一个红色报错就开始搜文案，实际上往上一屏翻，真正的第一现场往往在那里。

6.3 SDK 版本与工程配置不匹配的典型表现

症状：一堆接口标红，提示找不到某个类或方法；或者编译报某个 API 在当前版本不可用。

排查顺序：看工程配置里的 compatibleSdkVersion → 对照 IDE 里实际装了哪些版本的 SDK → 看报错的那个接口属于哪个 API 版本。

根因：配置里写的版本比实际装的低，导致高版本接口全部不可见；或者工程是从别处拷来的，配置里写着某个你没装的版本。

修复：两条路。要么把配置里的版本调到和已装 SDK 一致，要么补装对应版本的 SDK。我建议后者，因为改配置可能让工程失去某些原本该有的能力，而且如果这个工程是要和别人协作的，改配置会影响到别人。补装 SDK 时记得在 SDK 管理界面勾选对应的 ArkTS 声明文件，只装运行时是不够的，标红就是因为声明文件缺失导致 IDE 无法解析。

6.4 模拟器起不来、黑屏、卡开机动画的排查顺序

这类问题的排查要按"从宿主到客体"的顺序来，别一上来就重装模拟器。

第一步，确认虚拟化能力可用。Windows 上打开任务管理器看"虚拟化"是否为已启用；没启用就去 BIOS 里开。这是最常见也最容易被忽略的一条，很多人在这里卡两个小时。

第二步，确认镜像完整。设备管理器里能看到镜像状态，如果显示大小异常或者有校验失败标记，删掉重下。

第三步，调整资源分配。内存给太少会卡在启动阶段，给太多又可能和宿主争抢。4 GB 是个安全值，先按这个跑通再往上调。

第四步，看模拟器日志。模拟器启动失败时，日志里会明确写出是内核加载失败、磁盘镜像损坏还是资源不足。养成先看日志再动手的习惯，比反复点"重启"有效得多。

第五步，如果以上都正常但仍然黑屏，试试冷启动（清数据后重启）而不是热启动。有些状态下系统镜像的临时数据会残留，冷启动能清掉。

提示：模拟器和 IDE 之间的连接断掉时，IDE 里可能显示设备还在但运行按钮点了没反应。这时候先hdc list targets看一眼设备到底在不在，再决定是重启模拟器还是重启 IDE 里的设备连接服务。直接杀掉 IDE 重开是成本最高的做法，尽量放在最后。

7. 把环境调顺手：内存、索引与常用设置

环境能跑和用着舒服是两回事。下面这些设置是我每台新机器必调的，加起来十分钟，能换来长期的顺畅。

7.1 内存与堆参数的调整

IDE 的堆内存上限写在安装目录下的一个配置文件里（Windows 上是bin目录下的.vmoptions文件，macOS 上是应用包内对应位置）。默认值通常比较保守，在 16 GB 以上的机器上可以适当调高。要找的是一行长这样的配置：

-Xmx2048m

把数字调大，比如 16 GB 内存的机器调到 4096m，32 GB 的调到 6144m 或 8192m。不要贪心调到和物理内存一样大，堆开得太大反而会让垃圾回收的停顿变长，感受上是"平时很快，偶尔卡死一下"。调完之后重启 IDE 生效。

另一个容易忽略的是构建进程的内存。hvigor 的构建是独立进程跑的，如果大型工程编译时报内存溢出，要调的是构建进程的参数而不是 IDE 的堆。这类参数通常能在构建配置或者环境变量里指定，具体位置随版本变化，思路是"报错信息里提到堆溢出，就去调对应的那个进程，别乱调一气"。

7.2 索引范围与缓存清理

IDE 的智能提示、跳转、全局搜索全靠索引。索引范围越大越慢，所以要把不该索引的目录排除掉。工程里的build、.hvigor、oh_modules（依赖目录）这三类目录完全可以排除，它们的文件量大、变动频繁，索引它们纯属浪费。

排除的方式是在设置里找到文件类型或目录排除的配置项，把上述目录加上。加完之后 IDE 会自动重排索引，感受上是搜文件名快了一截。

缓存清理要分清楚两种情况。一种是"索引乱了"，表现为跳转跳到错误位置、明明存在的符号标红，这时候用"清理缓存并重启"的功能，让 IDE 重新建索引，耗时几分钟但能解决大部分玄学问题。另一种是"构建产物脏了"，表现为改了代码但运行结果没变、或者报一些奇怪的资源冲突，这时候删的是工程里的build目录和.hvigor目录，然后重新同步。两种清理作用在不同的层，别搞混。

还有一处缓存很容易被忽略：ohpm 的全局缓存在用户目录下，长期使用会积累到几个 G，而且偶尔会出现某个包下载了一半留下的损坏缓存，导致依赖解析莫名失败。遇到"这个包明明存在却说找不到"的时候，把缓存里对应包删掉重新拉一次，往往就好了。

7.3 几个真正提升效率的设置

关闭不用的插件。IDE 插件多了启动慢，把用不上的关闭，尤其是各种语言支持和示例插件，只留 ArkTS 相关的。

打开自动导入。写 ArkTS 时需要大量 import，自动导入能省掉大量手动敲路径的时间，配好之后输入类名就能自动补上引用。

配置代码格式化规则。团队协作时这点很重要，缩进、引号、行宽这些统一了，后面看 diff 才不会被格式化噪音淹没。规则文件可以随工程走，这样别人拉下来就自动生效。

熟悉 hdc 的几条常用命令。图形界面能做的事有限，命令行有时候更快：

hdc list targets # 看已连接设备 hdc shell # 进入设备 shell hdc install xxx.hap # 手动安装包，排查安装问题时很有用 hdc file send 本地路径 设备路径 # 往设备推文件 hdc hilog # 看设备日志，排查运行时问题的主力

hdc hilog这条我要单独说，它是排查运行时问题的核心工具，比在 IDE 的日志面板里翻要灵活得多，可以按 tag 过滤、可以重定向到文件。刚开始可能会被满屏日志淹没，但用几次就熟了。

8. 版本升级与多版本共存的实际处理

环境搭好之后，下一个会遇到的问题是"新版本出来了要不要升"。这个问题没有统一答案，但有判断方法。

8.1 升级之前先看清楚改了什么

升级 IDE 大版本时，最先要看的是构建工具链的版本变化。hvigor 的版本升级有时会引入不兼容的配置项变更，表现是旧工程的构建脚本在新版本下报错。这类变更通常会在发布说明里列出，花五分钟扫一眼"不兼容变更"那一节，比升级之后花两小时排错划算。

我自己的策略是：主力工程不跟着最新版走，另开一台机器或者用另一个用户目录跑最新版做验证。等最新版稳定一到两个小版本，再把主力环境升上去。IDE 装了新版本之后，旧版本的配置通常会被迁移，但迁移不是无损的，工作区布局、插件、缓存的兼容性都可能出问题。

8.2 旧工程迁到新 IDE 的具体动作

真要迁的时候，按这个顺序来：

先备份。把整个工程目录压缩一份，包括那些看起来是临时文件的配置目录。回滚的成本远低于重来。

再单独升级工具链。打开旧工程后先不要跑，去构建配置里把 hvigor 版本、依赖版本逐个确认一遍，看新 IDE 提示了哪些需要更新。依赖升级一次只升一组，升完同步一次，跑一次，确认没问题再升下一组。一次性全升的后果是出问题时不知道该怪谁。

然后处理废弃接口。新版本通常会把一批旧接口标记为废弃，编译时会给出警告。这些警告不要留着，随手改成新接口，否则下一个大版本里它们就变成错误了。

最后过一遍签名和打包。签名材料在新版本下有时候需要重新生成，尤其是换了签名算法或者证书格式的情况。打包出 APP 之后装到真机上验证一遍，确保发布链路是通的。

多版本共存这件事也要提一句：不同大版本的 IDE 可以装在不同的目录下，互不影响，但要注意 SDK 目录和缓存目录的复用问题。如果两个版本共用同一个 SDK 目录，低版本可能会把高版本的 SDK 标记为"未知版本"，反过来也一样。我的做法是每个 IDE 大版本配一个独立的 SDK 目录，磁盘多占一点，但省掉了一堆解释不清的冲突。

8.3 一个容易被忽略的收尾动作

升级完、迁完、跑通之后，把这一版的环境信息记下来：IDE 版本号、SDK 版本、hvigor 版本、ohpm 版本、Node 版本。写在工程根目录的一个说明文件里，和代码一起提交。

这件事看起来多余，但经历过一次"半年前能跑的工程现在跑不起来、又不知道当时是什么环境"之后，你就会明白它的价值。环境问题最难排查的地方在于信息缺失，把版本信息固化下来，等于给自己和协作者留了一条回溯的路。

我在实际带人的过程中发现，新手卡在环境搭建上的时间，八成不是因为步骤难，而是因为出问题时不知道往哪看。把上面这些排查链路走一遍，下次换个版本、换台机器，你也能自己走通，而不是每次都从零开始搜教程。