报错咨询：指令'versionCode'无效，合法指令为REMOVE、REPLACE、STRICT

Hey, I’ve run into this exact error before when working on Android projects—let me break down what’s going on and how to fix it.

原因分析 #

This error pops up when you’re working with Android Manifest merging (either via Gradle or direct Manifest tooling) and you’ve mixed up operation instructions with the Manifest property you want to modify.

The key issue: versionCode is a property in your Android Manifest, not a valid manipulation instruction. The only instructions the merging tool accepts are REMOVE, REPLACE, and STRICT.

For example, you might have written invalid config like this:

• In Gradle (wrong):

  android {
      defaultConfig {
          manifestPlaceholders = [
              versionCode: "REPLACE 123"  // ❌ Treating versionCode as an instruction
          ]
      }
  }
  

• In the Manifest file (wrong):

  <manifest xmlns:tools="http://schemas.android.com/tools">
      <application tools:versionCode="REPLACE 123" ...>  <!-- ❌ Using versionCode as an instruction -->
      </application>
  </manifest>
  

解决方法 #

Fixing this just means clarifying the relationship between instructions and the properties you want to modify. Here are the two most common scenarios:

1. Setting/modifying versionCode via Gradle #

You don’t need special instructions here—just set the value directly in your defaultConfig or product flavors:

android {
    defaultConfig {
        versionCode 123  // ✅ Directly set the numeric version code
        versionName "1.2.3"
    }

    // If you need variant-specific values
    productFlavors {
        free {
            versionCode 123
        }
        paid {
            versionCode 124
        }
    }
}

2. Using Manifest tools to enforce merging rules #

If you need to resolve merge conflicts (e.g., force replacing versionCode from a library manifest), use the valid instructions (REPLACE, REMOVE, STRICT) and point them at the versionCode property:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Force replace versionCode during merge -->
    <application 
        android:versionCode="123"
        tools:replace="android:versionCode"  <!-- ✅ Use REPLACE instruction on the versionCode property -->
        ...>
    </application>
</manifest>

Other valid instruction examples:

• tools:remove="android:allowBackup": Remove the allowBackup property from the merged manifest
• tools:strict="android:versionCode": Throw an error if there’s a conflict on versionCode (forces you to resolve it explicitly)

内容的提问来源于stack exchange，提问作者khalid