Skip to main content
Version: Next
新架构实战课 实操 + 基建 + 原理全维度包揽,抢先掌握 React Native 新架构精髓 立即查看 >

Headless JS(后台任务)

Headless JS 是一种使用 js 在后台执行任务的方法。它可以用来在后台同步数据、处理推送通知或是播放音乐等等。


首先我们要通过AppRegistry来注册一个异步函数,这个函数我们称之为“任务”。注册方式类似在 index.js 中注册 RN 应用:

import { AppRegistry } from 'react-native';
AppRegistry.registerHeadlessTask('SomeTaskName', () =>

然后创建 require 中引用的SomeTaskName.js文件:

module.exports = async taskData => {
// 要做的任务

你可以在任务中处理任何事情(网络请求、定时器等等),但唯独不要涉及用户界面!在任务完成后(例如在 promise 中调用 resolve),RN 会进入一个“暂停”模式,直到有新任务需要执行或者是应用回到前台。

Java 端的 API


package com.your_application_name;
import android.content.Intent;
import android.os.Bundle;
import com.facebook.react.HeadlessJsTaskService;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.jstasks.HeadlessJsTaskConfig;
import javax.annotation.Nullable;

public class MyTaskService extends HeadlessJsTaskService {

protected @Nullable HeadlessJsTaskConfig getTaskConfig(Intent intent) {
Bundle extras = intent.getExtras();
if (extras != null) {
return new HeadlessJsTaskConfig(
5000, // 任务的超时时间
false // 可选参数:是否允许任务在前台运行,默认为false
return null;


<service android:name="com.example.MyTaskService" />

好了,现在当你启动服务时(例如一个周期性的任务或是响应一些系统事件/广播),JS 任务就会开始执行。例如:

Intent service = new Intent(getApplicationContext(), MyTaskService.class);
Bundle bundle = new Bundle();

bundle.putString("foo", "bar");



By default, the headless JS task will not perform any retries. In order to do so, you need to create a HeadlessJsRetryPolicy and throw a specfic Error.

LinearCountingRetryPolicy is an implementation of HeadlessJsRetryPolicy that allows you to specify a maximum number of retries with a fixed delay between each attempt. If that does not suit your needs then you can easily implement your own HeadlessJsRetryPolicy. These policies can simply be passed as an extra argument to the HeadlessJsTaskConfig constructor, e.g.

HeadlessJsRetryPolicy retryPolicy = new LinearCountingRetryPolicy(
3, // Max number of retry attempts
1000 // Delay between each retry attempt
return new HeadlessJsTaskConfig(

A retry attempt will only be made when a specific Error is thrown. Inside a headless JS task, you can import the error and throw it when a retry attempt is required.


import {HeadlessJsTaskError} from 'HeadlessJsTask';
module.exports = async (taskData) => {
const condition = ...;
if (!condition) {
throw new HeadlessJsTaskError();

If you wish all errors to cause a retry attempt, you will need to catch them and throw the above error.


  • The function passed to setTimeout does not always behave as expected. Instead the function is called only when the application is launched again. If you just need to wait, use the retry functionality.
  • 默认情况下,如果应用正在前台运行时尝试执行任务,那么应用会崩溃。这是为了防止开发者在任务中处理太多逻辑而拖慢用户界面。如果你必须要这么做,那么可以设置第四个参数为false来更改这一限制。
  • 如果你是通过BroadcastReceiver来启动的服务,那么谨记在从onReceive()返回之前要调用HeadlessJsTaskService.acquireWakeLockNow()


我们可以使用 Java API 来开启一个 service。. First you need to decide when the service should be started and implement your solution accordingly. Here is a simple example that reacts to network connection change.

Following lines shows part of Android manifest file for registering broadcast receiver.

<receiver android:name=".NetworkChangeReceiver" >
<action android:name="" />

Broadcast receiver then handles intent that was broadcasted in onReceive function. This is a great place to check whether your app is on foreground or not. If app is not on foreground we can prepare our intent to be started, with no information or additional information bundled using putExtra (keep in mind bundle can handle only parcelable values). In the end service is started and wakelock is acquired.

public class NetworkChangeReceiver extends BroadcastReceiver {

public void onReceive(final Context context, final Intent intent) {
if (!isAppOnForeground((context))) {
boolean hasInternet = isNetworkAvailable(context);
Intent serviceIntent = new Intent(context, MyTaskService.class);
serviceIntent.putExtra("hasInternet", hasInternet);

private boolean isAppOnForeground(Context context) {
ActivityManager activityManager = (ActivityManager) context.getSystemService(Context.ACTIVITY_SERVICE);
List<ActivityManager.RunningAppProcessInfo> appProcesses =
if (appProcesses == null) {
return false;
final String packageName = context.getPackageName();
for (ActivityManager.RunningAppProcessInfo appProcess : appProcesses) {
if (appProcess.importance ==
ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND &&
appProcess.processName.equals(packageName)) {
return true;
return false;

public static boolean isNetworkAvailable(Context context) {
ConnectivityManager cm = (ConnectivityManager)
NetworkInfo netInfo = cm.getActiveNetworkInfo();
return (netInfo != null && netInfo.isConnected());