👋 你好，欢迎来到我的博客！我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者，正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来，也为了和更多同路人互相启发，我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向：ArkTS 语言基础、HarmonyOS 原生应用（Stage 模型、UIAbility/ServiceAbility）、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战，以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏：从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘，让每篇都有可落地的代码与方法论。
  💡 我相信：写作是把知识内化的过程，分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长，欢迎关注我，一起交流进步！🚀

前言

下载资源、上传文件、音乐播放、持续定位这类业务有一个很容易出现的理解偏差：页面退到后台，不等于页面里的 ArkTS 代码还能无限期继续执行。

HarmonyOS 会对后台应用进行资源管控。华为官方在“后台任务合理使用”中明确说明：普通应用退到后台后，进程可能在较短时间内被挂起；对于确实需要继续执行的业务，系统提供短时任务、长时任务、延迟任务等受约束的后台机制。长时任务适用于数据传输、音频播放、录音、定位导航、蓝牙、多设备互联等用户可感知、需要持续运行的场景。

这篇文章不把所有后台能力混在一起讲，而是聚焦一个具体问题：

一个正在执行数据传输的 HarmonyOS 应用切到后台后，如何通过 Background Tasks Kit 申请 dataTransfer 长时任务，并正确完成启动、通知跳转和停止。

文中的代码按华为官方 backgroundTaskManager 接口定义整理为最小实践。由于这里没有实际 HarmonyOS 工程和设备环境，不声称代码已经编译或真机运行，正式使用前仍应在自己的目标 SDK 与设备上验证。

一、前台代码不能直接当成“后台常驻代码”

先把一个概念拆开：代码正在执行和应用获得后台持续运行资格不是一回事。

应用处在前台时，业务代码可以正常执行。切换到后台以后，系统需要兼顾功耗、流畅度和资源分配，因此会对后台应用进行管控。没有申请适当后台任务的普通应用，不能把“某个 Promise 还没结束”“某个定时器还在跑”理解成系统承诺它会一直运行。官方给出的后台任务分类中，“无后台任务”的应用退到后台后可能很快进入挂起状态。

所以对于大文件上传、资源包下载这样的业务，正确思路不是想办法让页面“永远活着”，而是先判断业务属于哪一种系统认可的后台场景。

这也是 Background Tasks Kit 存在的意义。

二、短时任务和长时任务不是按代码长短来区分

HarmonyOS 官方把短时任务和长时任务的使用范围划分得比较清楚。

类型	更适合的业务	后台行为
短时任务	小文件下载、缓存、信息发送等实时性较高但耗时不长的工作	获得有限执行时间
长时任务	数据传输、音频播放、录音、定位导航等持续业务	在符合约束并保持任务有效期间，应用不会因普通后台策略而直接挂起
延迟任务	软件更新、信息收集等实时性不高的任务	由系统按条件统一调度

官方资料还明确指出，短时任务存在时间配额；旧版 API 文档给出的普通情况下最大申请时间为 3 分钟，低电量场景还会进一步缩短。

因此，一个可能持续较长时间的资源包下载，不应该通过反复申请短时任务来模拟长期运行。

华为针对游戏资源包下载也有明确 FAQ：对于游戏前台开始下载、随后切到后台继续下载资源包的情况，可以申请 dataTransfer 类型的长时任务。

三、HarmonyOS 7 下先确认版本关系

本文以当前 HarmonyOS 7 为背景。

华为在 2026 年的升级适配资料中明确说明，HarmonyOS 7.0 对应 API 26.0.0。从 26.0.0 开始，SDK API 版本号也改为了语义化版本格式。

但这里需要特别说明：

backgroundTaskManager 并不是 HarmonyOS 7 才新增的能力。

官方 API 参考显示：

• @ohos.resourceschedule.backgroundTaskManager 首批接口从 API version 9 开始支持；
• startBackgroundRunning(context, bgModes, wantAgent) 的多类型版本从 API version 12 开始提供；
• updateBackgroundRunning() 同样从 API version 12 开始支持；
• HarmonyOS 7 / API 26 又进一步加入了 ContinuousTaskRequest、特殊场景授权等能力。

本文的数据传输场景并不需要强行使用 API 26 新增的“特殊场景处理”模式，因此继续采用官方已经长期提供的 dataTransfer + WantAgent 路径，更容易把基本机制讲清楚。

四、哪些业务可以申请长时任务

长时任务并不是一个通用的“后台保活开关”。

官方 BackgroundMode 定义中可以看到数据传输、音视频播放、录制、定位导航、蓝牙相关业务、多设备互联等类型；不同版本还会扩充特定模式，并可能带有设备限制。比如旧版接口定义中的 TASK_KEEPING 就明确只面向 2in1 设备。

这意味着开发时不能这么做：

我的业务想后台运行
        ↓
随便选一个 BackgroundMode
        ↓
调用 startBackgroundRunning

应该反过来：

确认业务真实类型
        ↓
确认官方是否允许对应长时任务
        ↓
module.json5 声明相同的 backgroundModes
        ↓
申请权限
        ↓
启动业务与长时任务
        ↓
业务结束立即停止

本文选择的数据传输，对应配置字符串为：

dataTransfer

旧版 BackgroundMode.DATA_TRANSFER 枚举值则表示数据传输类型。

五、最小实践：给数据传输业务增加后台执行资格

这里假设应用已经有自己的上传或下载实现。

本文不另外引入网络库，避免把“后台任务管理”和“网络传输 API”混在一起。我们的目标只有一个：

开始传输时申请 dataTransfer 长时任务，传输结束、失败或取消时释放长时任务。

流程可以整理成：

用户开始下载
   ↓
创建 WantAgent
   ↓
startBackgroundRunning()
   ↓
执行原有数据传输
   ↓
成功 / 失败 / 用户取消
   ↓
stopBackgroundRunning()

真正需要注意的不是下载函数本身，而是长时任务必须和真实业务生命周期对应起来。

六、先配置 KEEP_BACKGROUND_RUNNING

startBackgroundRunning() 官方接口要求权限：

ohos.permission.KEEP_BACKGROUND_RUNNING

同时，Ability 需要声明对应的后台运行模式。官方音频等实践同样采用“权限 + backgroundModes”组合配置。

数据传输场景可以在 module.json5 中按下面的结构配置：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "backgroundModes": [
          "dataTransfer"
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
      }
    ]
  }
}

这里有两个配置不能混淆：

requestPermissions 解决的是应用是否具备后台运行权限。

backgroundModes 描述的是这个 Ability 具体要申请哪一种长时任务类型。

如果只配置权限、没有声明合法的后台模式，后面调用接口仍可能因为长时任务校验失败而报错。官方 9800005 错误码的可能原因里就明确包含 backgroundModes 未配置、模式无效或类型不匹配。

七、为什么还要创建 WantAgent

长时任务具有用户可感知属性。

startBackgroundRunning() 的参数里除了 Context 和后台模式，还需要 WantAgent。官方接口说明中明确指出，这个 WantAgent 用于指定用户点击长时任务通知后需要跳转到的页面。

因此它不是一段可有可无的模板代码。

可以先封装一个最小创建函数：

import { wantAgent, WantAgent } from '@kit.AbilityKit';

async function createBackgroundWantAgent(): Promise<WantAgent> {
  const info: wantAgent.WantAgentInfo = {
    wants: [
      {
        bundleName: 'com.example.backgrounddemo',
        abilityName: 'EntryAbility'
      }
    ],
    actionType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [
      wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG
    ]
  };

  return await wantAgent.getWantAgent(info);
}

其中 bundleName 必须替换成实际工程的 Bundle Name。

这里真正需要关注的是三个参数：

wants 指定通知点击后的目标 Ability；START_ABILITY 表示执行启动 Ability 的动作；UPDATE_PRESENT_FLAG 则是官方示例使用的 WantAgent 标志。官方 backgroundTaskManager 示例也使用了相同的组织方式。

八、调用 startBackgroundRunning

如果项目基线已经高于 API version 12，可以采用返回 ContinuousTaskNotification 的 Promise 版本：

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

export class DataTransferBackgroundTask {
  private context: common.UIAbilityContext;
  private running: boolean = false;
  private notificationId: number = 0;

  constructor(context: common.UIAbilityContext) {
    this.context = context;
  }

  async start(): Promise<void> {
    if (this.running) {
      return;
    }

    try {
      const agent = await createBackgroundWantAgent();

      const modes: Array<string> = ['dataTransfer'];

      const result: backgroundTaskManager.ContinuousTaskNotification =
        await backgroundTaskManager.startBackgroundRunning(
          this.context,
          modes,
          agent
        );

      this.notificationId = result.notificationId;
      this.running = true;

      console.info(
        `continuous task started, notificationId=${this.notificationId}`
      );
    } catch (error) {
      const err = error as BusinessError;
      console.error(
        `startBackgroundRunning failed, code=${err.code}, message=${err.message}`
      );
      throw error;
    }
  }
}

这里采用：

['dataTransfer']

而不是随手传一个字符串，是因为官方 API 规定 bgModes 必须来自受支持的长时任务配置项。API version 12 起的这个重载返回 ContinuousTaskNotification，其中包括 notificationId。

这个通知 ID 对数据传输类型尤其有用：官方 API 示例明确说明，上传下载类型可以使用返回的通知 ID进一步更新通知，例如展示带进度的模板通知。

不过要注意：获得长时任务资格并不会替你执行下载。

startBackgroundRunning() 管的是后台调度资格，真正的数据传输仍然需要由网络层完成。

九、把它接入真实下载生命周期

业务层可以保持一个非常清楚的结构：

async function startDownload(): Promise<void> {
  await backgroundTask.start();

  try {
    // 在这里调用项目原有的数据传输代码。
    // await downloadService.download(...);

  } catch (error) {
    console.error(`download failed: ${JSON.stringify(error)}`);
    throw error;
  } finally {
    await backgroundTask.stop();
  }
}

这里的关键不是 try/catch，而是 finally。

因为：

• 下载成功，要停止长时任务；
• 下载失败，要停止；
• 用户取消，也要停止。

不要只在成功回调里写 stopBackgroundRunning()。

否则网络已经结束，后台任务却还处于有效状态，系统看到的业务状态与真实业务状态就不一致了。

十、停止长时任务

对应的停止逻辑可以继续放进控制器：

async stop(): Promise<void> {
  if (!this.running) {
    return;
  }

  try {
    await backgroundTaskManager.stopBackgroundRunning(this.context);

    this.running = false;
    this.notificationId = 0;

    console.info('continuous task stopped');
  } catch (error) {
    const err = error as BusinessError;
    console.error(
      `stopBackgroundRunning failed, code=${err.code}, message=${err.message}`
    );
    throw error;
  }
}

官方 Promise 版本定义为：

stopBackgroundRunning(context: Context): Promise<void>

它用于取消已申请的长时任务。

十一、updateBackgroundRunning() 不是“更新下载进度”

这里特别容易理解错。

看到：

updateBackgroundRunning()

很多人第一反应是：

下载到 50% 了，是不是调用它更新任务进度？

不是。

官方接口定义很明确：

updateBackgroundRunning(
  context: Context,
  bgModes: string[]
): Promise<ContinuousTaskNotification>

它更新的是长时任务类型，并不是业务进度。调用它之前还必须已经通过 startBackgroundRunning() 启动长时任务。

而对于本文的 dataTransfer 场景，还有更严格的一点：

官方当前 9800005 错误码说明直接列出了一个可能原因：

数据传输类型不支持通过更新接口更新长时任务类型。

所以数据下载从 20% 到 60% 时，不应该写：

backgroundTaskManager.updateBackgroundRunning(
  context,
  ['dataTransfer']
);

这不是它的用途。

如果业务希望向用户展示下载进度，应围绕 startBackgroundRunning() 返回的 notificationId 设计通知更新；不要把“更新通知内容”和“修改后台任务类型”混在一起。官方的 API version 12 示例也专门提到了上传下载类型可以利用该通知 ID 更新通知。

这是整套 API 中很值得单独记住的一点。

十二、为什么业务完成后一定要 stop

长时任务不是“申请以后放着不管”的后台保活能力。

华为的后台任务体验规范明确说明，对于长时任务，应用在任务运行期间不会按普通后台规则直接挂起；但任务结束以后如果没有取消后台任务，应用进程可能被系统终止。

换句话说：

任务开始 → startBackgroundRunning
任务结束 → stopBackgroundRunning

这两个动作应该成对出现。

实际工程中建议至少覆盖下面几条路径：

正常完成
网络错误
服务端错误
用户取消
业务主动中止
页面/业务模块进行异常清理

不要把 stopBackgroundRunning() 简单绑定到“页面退出”。

比如用户从下载页返回首页，但下载仍然合法持续进行，这时真正决定要不要停止的应该是传输任务本身是否结束，而不是某个 ArkUI 页面是否销毁。

十三、HarmonyOS 7 的新接口要不要用

HarmonyOS 7 / API 26 的 Background Tasks Kit 已经增加了新的长时任务能力，包括：

ContinuousTaskRequest
BackgroundTaskMode.MODE_SPECIAL_SCENARIO_PROCESSING
BackgroundTaskSubmode
checkSpecialScenarioAuth()
requestAuthFromUser()

等接口。

华为当前的视频后台导出最佳实践就使用了新的 ContinuousTaskRequest，配合：

specialScenarioProcessing
KEEP_BACKGROUND_RUNNING_SPECIAL_SCENARIO

实现媒体处理类特殊场景后台执行。

但这个能力解决的是另一类问题。

本文讲的是官方已经明确支持的普通：

dataTransfer

因此没有必要仅仅因为项目运行在 HarmonyOS 7，就把数据传输强行改造成特殊场景后台任务。

版本升级不等于旧的、仍然有效的接口都应该被新 API 替代。

真正应该做的是根据业务类型选择匹配的官方机制。

十四、失败以后先从这些错误码查

startBackgroundRunning()、stopBackgroundRunning() 和 updateBackgroundRunning() 的问题，不建议只打印一句“申请后台失败”。

至少保留：

catch (error) {
  const err = error as BusinessError;
  console.error(`code=${err.code}, message=${err.message}`);
}

官方接口和错误码文档中，与长时任务最直接相关的错误包括：

错误码	优先检查方向
201	权限是否正确声明
401	参数是否缺失、类型是否错误
9800001	内存操作异常
9800002	Parcel 读写异常
9800003	IPC / 内部通信异常
9800004	系统服务异常
9800005	长时任务校验失败
9800006	长时任务通知校验失败
9800007	长时任务信息存储失败

其中最应该先看的往往是 9800005。

它不是单一原因，而是一组长时任务校验问题。官方当前错误码文档列出的可能情况包括：

• 重复申请；
• 重复取消；
• backgroundModes 没有配置合法类型；
• 后台任务模式无效；
• 主类型和子类型不匹配；
• continuousTaskId 无效；
• 某些模式存在设备要求；
• 数据传输类型进行了不受支持的更新操作等。

所以看到 9800005 时，不要第一时间怀疑网络层。

十五、推荐的排查顺序

这类问题实际排查时，可以固定成一条链路：

先确认 SDK/API 版本。

如果项目是 HarmonyOS 7，应明确当前 API 26.0.0 的编译和目标版本；如果项目维护的是更低 API 基线，则根据该版本接口定义处理。

再检查 module.json5。

确认同时存在：

"backgroundModes": [
  "dataTransfer"
]

以及：

"name": "ohos.permission.KEEP_BACKGROUND_RUNNING"

然后核对调用类型。

如果配置的是：

dataTransfer

代码里就不要申请与真实业务无关的音频、定位等模式。

接着确认是否重复启动。

业务控制器自己保存运行状态，避免同一个数据传输过程反复执行 startBackgroundRunning()。

最后检查停止路径。

正常完成、失败和用户取消是否最终都会执行 stopBackgroundRunning()。

十六、几个容易混淆的概念

1. Worker 不等于长时后台任务

Worker 解决的是并发和线程问题。

官方并发文档中把“常驻任务并发”描述为将耗时逻辑放到 Worker 后台线程运行，以避免阻塞 UI 主线程。它和 Background Tasks Kit 的“应用退到后台后是否获得持续运行资格”是两个维度。

因此：

Worker = 解决在哪个线程执行
长时任务 = 解决应用进入后台后的系统调度资格

把下载放进 Worker，并不能自动获得后台持续运行能力。

2. 长时任务不等于任意保活

只有符合官方定义的业务类型才应该申请。

不能为了保住一个普通定时器就声明：

dataTransfer

业务实际在做什么，应该和申报的任务类型一致。

3. WantAgent 不负责启动后台业务

WantAgent 在这里主要服务于长时任务通知点击后的跳转。

真正业务仍由应用自己启动。

4. updateBackgroundRunning 不等于刷新进度

它更新的是任务类型。

数据传输进度展示应走通知更新逻辑，而不是不停更新后台模式。

开发经验总结

把 HarmonyOS 长时任务真正用对，核心并不是多写几个 API，而是建立正确的生命周期关系：

真实业务开始
   ↓
申请与业务匹配的长时任务
   ↓
系统允许该业务在后台持续执行
   ↓
业务完成 / 失败 / 取消
   ↓
立即停止长时任务

对于下载和上传类业务，本文最需要记住四件事。

第一，应用进入后台后不能假设普通前台代码会无限执行；需要根据业务选择正式后台机制。

第二，数据传输属于官方支持的长时任务场景，资源包下载切后台继续执行也有华为官方 FAQ 作为依据。

第三，KEEP_BACKGROUND_RUNNING、backgroundModes、WantAgent 和 startBackgroundRunning() 是一条完整链路，不能只调用一个接口就期待系统自动处理其他部分。

第四，业务结束一定要取消长时任务；updateBackgroundRunning() 也不要误当成下载进度更新接口，尤其是 dataTransfer 类型本身不支持通过该接口修改长时任务类型。

如果正在排查“前台下载正常，一切到后台进度就不走”的问题，可以先别急着改网络层。先检查应用究竟有没有建立与真实数据传输生命周期一致的长时任务，这一步往往比继续加定时器或者换线程更关键。

📝 写在最后

如果你觉得这篇文章对你有帮助，或者有任何想法、建议，欢迎在评论区留言交流！你的每一个点赞 👍、收藏 ⭐、关注 ❤️，都是我持续更新的最大动力！

我是一个在代码世界里不断摸索的小码农，愿我们都能在成长的路上越走越远，越学越强！

感谢你的阅读，我们下篇文章再见～👋

✍️ 作者：菜鸟不学编程
🧵 本文原创，转载请注明出处。