--init-script是唯一精准控制单次构建初始化逻辑的方式，支持多次指定、按序执行，仅接受真实存在的.gradle文件，不支持.kts；路径需明确指定，语法错误会直接报错退出。

可以直接用 --init-script 参数指定，这是最明确、最可控的方式。

命令行传入 --init-script 的写法和限制

Gradle 支持在任意命令前加 --init-script，后面紧跟脚本路径（绝对或相对）：

• gradle --init-script ./my-init.gradle build —— 相对路径，当前目录下找
• gradle --init-script /home/user/.gradle/init.d/company.gradle build —— 绝对路径，推荐用于复用脚本
• 可重复使用多次：gradle --init-script a.gradle --init-script b.gradle tasks，按参数顺序执行
• 路径必须是真实存在的 .gradle 文件，不能是目录，也不能是 .gradle.kts（Kotlin DSL 初始化脚本不支持命令行直接传入）
• 如果脚本语法错误，Gradle 会直接报错退出，错误信息里会包含 init script 字样，例如：Could not compile initialization script '...

  init.gradle 放进 ~/.gradle/ 目录是否算“命令行指定”

  不算。把文件放到 USER_HOME/.gradle/init.gradle 是**自动加载**行为，不经过命令行参数，属于全局默认初始化脚本。它会在所有构建中无条件执行，哪怕你没输任何 --init-script。这种做法适合企业统一配置，但不适合临时调试或项目级覆盖。

  • 优先级低于命令行 --init-script：如果同时存在命令行指定脚本和 ~/.gradle/init.gradle，前者先执行
  • 没有显式开关控制启用/禁用，想跳过得加 --no-daemon --no-build-cache 等也无效，只能临时重命名或移走该文件
  • 容易被团队成员无意修改或覆盖，不适合协作开发中的临时定制

  为什么不用 GRADLE_HOME/init.d/ 或 ~/.gradle/init.d/ 来“命令行指定”

  这两个目录下的 .gradle 文件是**自动发现并加载**的，不是靠命令行参数触发。它们的加载时机和顺序由 Gradle 内部规则决定（按字母序），无法用命令行临时增删或调整执行顺序。

  • 比如 ~/.gradle/init.d/a.gradle 和 b.gradle 会固定按 a→b 执行，你不能在某次构建中只跑 b
  • 目录方式适合长期稳定的环境策略（如公司统一镜像仓库配置），但不适合“这次构建我想试一个新 init 脚本”的场景
  • 如果你真想用目录方式又保持灵活性，可以配合软链接：ln -sf my-test.gradle ~/.gradle/init.d/current.gradle，再手动切换目标

  常见误操作和排查点

  实际用 --init-script 时，最容易卡在路径和作用域上：

  • 脚本里写的 allprojects { ... } 不生效？检查是否漏了 initscript 块——--init-script 加载的脚本本身不自动拥有 initscript 闭包，它直接运行在 Gradle 实例上，所以要配插件或依赖，得用 gradle.pluginRepositories 或 gradle.settingsEvaluated 等钩子
  • 脚本里改了 repositories，但 build.gradle 里还是连不上 Maven 中央库？因为 init 脚本的 repositories 配置默认只影响插件下载（pluginManagement），不影响项目依赖——得显式写 allprojects { repositories { ... } }
  • Mac/Linux 下路径含空格导致找不到文件？必须用引号包裹：gradle "--init-script" "my init.gradle" build
  • Windows 上用反斜杠 或未转义的 % 符号会解析失败，一律用正斜杠 / 或双反斜杠 \

  真正需要“命令行指定”的场景，基本就落在临时调试、CI 单次任务定制、或跨项目快速验证配置这三类上。--init-script 是唯一能精准控制“这一次跑什么初始化逻辑”的手段，其他方式都是静态绑定，改了就得动文件系统。