pindo 5.18.5 → 5.18.9

data/lib/pindo/module/android/android_build_helper.rb

@@ -73,16 +73,21 @@ module Pindo
             unless build_so_library(unity_dir)
               raise RuntimeError, "编译 Unity 模块 SO 库失败"
             end
-            copy_so_files(unity_dir, project_dir)
-            validate_unity_libs_state!(project_dir, stage: "导出后")
-
-            # SO 库拷贝完成后，重新配置主工程的 Java Home 和 Gradle 环境
-            puts "Unity SO库编译完成，切换到主工程编译环境"
-            Pindo::JavaEnvHelper.setup_java_home_from_project(project_dir, use_main: true)
-            Pindo::GradleHelper.check_gradle_with_project(project_dir, configure_main: true)
           else
             puts "未检测到 IL2CPP 目录，可能使用 Mono 后端，跳过 SO 库构建"
           end
+
+          # 无论 IL2CPP 或 Mono，均需要将 Unity 导出工程的关键产物同步回主工程：
+          # - unityLibrary/libs（Java/Kotlin 库）
+          # - unityLibrary/src/main/assets（StreamingAssets 等资源）
+          # - unityLibrary/src/main/jniLibs（若存在）
+          copy_so_files(unity_dir, project_dir)
+          validate_unity_libs_state!(project_dir, stage: "导出后")
+
+          # 同步完成后，重新配置主工程的 Java Home 和 Gradle 环境
+          puts "Unity 产物同步完成，切换到主工程编译环境"
+          Pindo::JavaEnvHelper.setup_java_home_from_project(project_dir, use_main: true)
+          Pindo::GradleHelper.check_gradle_with_project(project_dir, configure_main: true)
         else
           puts "警告：Unity 作为 lib 的工程，但未找到 Unity 目录"
         end
@@ -101,33 +106,81 @@ module Pindo
       build_type = debug ? "debug" : "release"
       raise "bundle_name 不能为空，Keystore 签名需要 Application ID" if bundle_name.nil? || bundle_name.empty?
 
-      unless Pindo::KeystoreHelper.apply_keystore_config(project_dir, build_type, bundle_id: bundle_name)
-        raise RuntimeError, "Keystore 签名配置失败"
-      end
-      puts "✓ Android 签名配置成功"
-
-      if workflow_name && !workflow_name.to_s.empty?
-        injector = Pindo::Android::WorkflowGradleInjector.new
-        ctx = injector.prepare!(
-          project_dir: project_dir,
-          workflow_name: workflow_name,
-          enable_pad: true
-        )
-        apk_path = nil
-        begin
-          apk_path = build_apk(project_dir, debug, workflow_build_type: ctx[:workflow_build_type])
-        ensure
-          injector.cleanup!(ctx)
+      apk_path = nil
+      begin
+        unless Pindo::KeystoreHelper.apply_keystore_config(project_dir, build_type, bundle_id: bundle_name)
+          raise RuntimeError, "Keystore 签名配置失败"
         end
-        # JKS 仅在 universal.apk 已成功产出后删除；失败则保留，便于排查（Gradle 注入已在 ensure 中恢复）
-        Pindo::KeystoreHelper.cleanup_managed_signing_paths! if apk_path && File.exist?(apk_path.to_s)
-        Pindo::Android::WorkflowGradleInjector.remove_project_pindo_tmp_dir!(project_dir)
-      else
-        # 兼容旧行为：仍会永久写入 PAD 相关变更（如需临时恢复，请传 workflow_name 走注入管线）
-        setup_play_asset_delivery(project_dir)
-        apk_path = build_apk(project_dir, debug)
-        Pindo::KeystoreHelper.cleanup_managed_signing_paths! if apk_path && File.exist?(apk_path.to_s)
+        puts "✓ Android 签名配置成功"
+
+        if workflow_name && !workflow_name.to_s.empty?
+          pad_persist = pad_persist_enabled?
+
+          # 永久 PAD：每次构建前清理旧的 *_pack，并从当前导出产物重新生成
+          # 注意：PAD 会移动 unityLibrary/src/main/assets 下的目录到 *_pack；
+          # 因此要保证在此之前已经把 Unity/ 导出产物同步回主工程（Unity as lib 分支已同步）。
+          setup_play_asset_delivery_persistent(project_dir) if pad_persist
+
+          injector = Pindo::Android::WorkflowGradleInjector.new
+          ctx = injector.prepare!(
+            project_dir: project_dir,
+            workflow_name: workflow_name,
+            enable_pad: !pad_persist
+          )
+          begin
+            apk_path = build_apk(project_dir, debug, workflow_build_type: ctx[:workflow_build_type])
+          ensure
+            injector.cleanup!(ctx)
+            Pindo::Android::WorkflowGradleInjector.remove_project_pindo_tmp_dir!(project_dir)
+          end
+        else
+          # 兼容旧行为：仍会永久写入 PAD 相关变更（如需临时恢复，请传 workflow_name 走注入管线）
+          setup_play_asset_delivery(project_dir)
+          apk_path = build_apk(project_dir, debug)
+        end
+      ensure
+        # 安全优先：无论成功/失败，均清理本次下载/拷贝到工程 signing/ 的签名文件，并恢复本次改动的 Gradle 签名配置与进程 ENV。
+        # 说明：这会降低“失败后保留签名文件便于排查”的便利性，但可以显著降低泄露风险。
+        Pindo::KeystoreHelper.cleanup_managed_signing_paths!
+        Pindo::KeystoreHelper.restore_managed_signing_config!
+        Pindo::KeystoreHelper.cleanup_managed_signing_env!
+      end
+    end
+
+    private def pad_persist_enabled?
+      # 默认开启永久 PAD（避免 workflow 注入管线在 cleanup 时删除 *_pack）
+      # 如需回到“临时 PAD（构建结束自动回滚）”，可显式设置：
+      #   export PINDO_PAD_PERSIST=0
+      val = ENV.fetch("PINDO_PAD_PERSIST", nil)
+      return true if val.nil?
+
+      v = val.to_s.strip.downcase
+      return true if v.empty?
+      return false if %w[0 false no off].include?(v)
+
+      true
+    end
+
+    # 永久 PAD：先清理旧的 *_pack，再从当前 assets 生成新的 pack
+    private def setup_play_asset_delivery_persistent(project_dir)
+      # 仅 Unity 导出工程才有 unityLibrary/src/main/assets
+      unity_assets = File.join(project_dir, "unityLibrary", "src", "main", "assets")
+      return unless File.directory?(unity_assets)
+
+      # 清理旧 pack：避免 assets 内容变化后残留旧 pack 目录导致重复/脏数据
+      Dir.glob(File.join(project_dir, "*_pack")).each do |dir|
+        next unless File.directory?(dir)
+
+        # 尽量只删除我们生成的模块：要求 build.gradle 存在且包含 asset-pack 插件
+        gradle = File.join(dir, "build.gradle")
+        next unless File.file?(gradle)
+        content = File.read(gradle)
+        next unless content.include?("com.android.asset-pack")
+
+        FileUtils.rm_rf(dir)
       end
+
+      setup_play_asset_delivery(project_dir)
     end
 
     def build_apk(project_path, debug, workflow_build_type: nil)
@@ -142,13 +195,6 @@ module Pindo
       main_module = Pindo::AndroidProjectHelper.get_main_module(project_path)
       raise ArgumentError, "无法找到主模块" unless main_module
 
-      keystore_config = Pindo::KeystoreHelper.get_keystore_config_from_project(
-        project_path,
-        debug,
-        workflow_build_type: workflow_build_type
-      )
-      raise ArgumentError, "无法从 build.gradle 中获取 keystore 信息" unless keystore_config
-
       build_tools = Pindo::AndroidProjectHelper.get_build_tools
       unless build_tools
         Funlog.error("无法继续构建：缺少必要的构建工具")
@@ -209,29 +255,27 @@ module Pindo
       end
       # --- END ---
 
-      # puts "解析 keystore 配置"
-      # 与 Gradle 对 storeFile 的生效顺序一致：常见写法为
-      #   storeFile file(System.getenv("RELEASE_KEYSTORE_PATH") ?: "signing/gxdebug.jks")
-      # apply_keystore_config 已在当前进程设置 RELEASE_*，Gradle 打 AAB 时走 ENV 指向的真实 jks；
-      # get_keystore_config_from_project 若只解析到 ?: 右侧占位路径，会与 AAB 实际签名不一致且文件可能不存在。
-      # 故：当 RELEASE_KEYSTORE_PATH 展开后文件存在时，bundletool 必须使用同一套 RELEASE_*（非「失败回退」）。
       kh = Pindo::KeystoreHelper
       env_ks = ENV[kh::ENV_RELEASE_KEYSTORE_PATH]
       env_ks_abs = env_ks && !env_ks.to_s.empty? ? File.expand_path(env_ks) : nil
-      gradle_ks = keystore_config[:store_file]
-
-      use_release_env = env_ks_abs && File.exist?(env_ks_abs)
-      if use_release_env
-        ks = env_ks_abs
-        ks_pass = ENV[kh::ENV_RELEASE_KEYSTORE_PASSWORD] || keystore_config[:store_password]
-        key_alias = ENV[kh::ENV_RELEASE_KEY_ALIAS] || keystore_config[:key_alias]
-        key_pass = ENV[kh::ENV_RELEASE_KEY_PASSWORD] || keystore_config[:key_password]
-      else
-        ks = gradle_ks || env_ks
-        ks = File.expand_path(ks.to_s) if ks && !ks.to_s.empty?
-        ks_pass = keystore_config[:store_password] || ENV[kh::ENV_RELEASE_KEYSTORE_PASSWORD]
-        key_alias = keystore_config[:key_alias] || ENV[kh::ENV_RELEASE_KEY_ALIAS]
-        key_pass = keystore_config[:key_password] || ENV[kh::ENV_RELEASE_KEY_PASSWORD]
+      # 签名信息只允许从环境变量读取，禁止从 build.gradle 解析值作为回退来源。
+      # 这样可以避免「环境变量缺失时悄悄退回到 Gradle 文本里的占位/历史明文」导致签名不一致。
+      ks = env_ks_abs
+      ks_pass = ENV.fetch(kh::ENV_RELEASE_KEYSTORE_PASSWORD, nil)
+      key_alias = ENV.fetch(kh::ENV_RELEASE_KEY_ALIAS, nil)
+      key_pass = ENV.fetch(kh::ENV_RELEASE_KEY_PASSWORD, nil)
+
+      missing_env = []
+      missing_env << kh::ENV_RELEASE_KEYSTORE_PATH if env_ks_abs.nil? || env_ks_abs.to_s.empty?
+      missing_env << kh::ENV_RELEASE_KEYSTORE_PASSWORD if ks_pass.to_s.empty?
+      missing_env << kh::ENV_RELEASE_KEY_ALIAS if key_alias.to_s.empty?
+      missing_env << kh::ENV_RELEASE_KEY_PASSWORD if key_pass.to_s.empty?
+      unless missing_env.empty?
+        raise RuntimeError, "缺少 Android release 签名所需环境变量：#{missing_env.join(', ')}"
+      end
+
+      unless File.exist?(ks)
+        raise RuntimeError, "Keystore 文件不存在: #{ks}"
       end
 
       ks_display = ks && !ks.to_s.empty? ? File.expand_path(ks.to_s) : ks.to_s
@@ -239,7 +283,7 @@ module Pindo
       # if workflow_build_type && !workflow_build_type.to_s.empty?
       #   puts "[bundletool] workflow buildType: #{workflow_build_type}"
       # end
-      # puts "[bundletool] 签名来源: #{use_release_env ? "RELEASE_KEYSTORE_PATH（文件存在，与 Gradle 打 AAB 一致）" : "build.gradle 解析 / ENV 兜底（非 RELEASE 路径或文件不存在时）"}"
+      # puts "[bundletool] 签名来源: RELEASE_* 环境变量（强制）"
       # puts "[bundletool] keyAlias: #{key_alias.inspect}（口令不落日志）"
 
       # 构建 APK
@@ -270,7 +314,7 @@ module Pindo
       end
 
       if ks.nil? || ks.to_s.empty?
-        raise RuntimeError, "Keystore 路径为空：无法从 build.gradle 解析签名配置，且未从环境变量获取到 #{Pindo::KeystoreHelper::ENV_RELEASE_KEYSTORE_PATH}"
+        raise RuntimeError, "Keystore 路径为空：未从环境变量获取到 #{Pindo::KeystoreHelper::ENV_RELEASE_KEYSTORE_PATH}"
       end
 
       unless File.exist?(ks)
@@ -314,12 +358,9 @@ module Pindo
                   end
 
       bundle_task = "#{prefix}#{task_name}"
-      skip_clean = Pindo::Options::GlobalOptionsState.instance[:skipclean]
-      # 任意 bundle 变体（含 debug）均先 clean，避免 aabresguard 等任务因残留输出报「文件已存在」；可通过 --skipclean 或 PINDO_SKIP_GRADLE_CLEAN=1 跳过
-      puts '  AAB 构建前先执行 Gradle clean（--skipclean 可跳过）' unless skip_clean
-      puts '  已跳过 Gradle clean（--skipclean）' if skip_clean
-
-      gradle_clean_resilient!(project_path) unless skip_clean
+      # 任意 bundle 变体（含 debug）均先 clean，避免 aabresguard 等任务因残留输出报「文件已存在」
+      puts '  AAB 构建前先执行 Gradle clean'
+      gradle_clean_resilient!(project_path)
 
       cmd = "cd \"#{project_path}\" && ./gradlew --no-daemon #{bundle_task}"
       system(cmd)
@@ -440,8 +481,7 @@ module Pindo
     def validate_unity_libs_state!(android_root, stage:)
       # 某些项目会将 unityLibrary 作为缓存/中间产物纳入仓库，但 libs 下的 .aar -> .srcaar
       # 符号链接目标是由 EDM4U/导出过程生成，初次拉取代码时可能为断链。
-      # 默认仍严格失败；可通过 --skipvalidate 或 PINDO_SKIP_UNITY_LIBS_VALIDATE=1 跳过
-      return if Pindo::Options::GlobalOptionsState.instance[:skipvalidate]
+      # 这里必须严格失败，避免后续构建阶段才出现不可读/缺失依赖导致更难定位的问题
 
       libs_dir = File.join(android_root, "unityLibrary", "libs")
       return unless File.directory?(libs_dir)

data/lib/pindo/module/android/android_config_helper.rb

@@ -6,7 +6,7 @@ require_relative 'android_project_helper'
 require_relative '../../base/executable'
 require_relative 'android_res_helper'
 require 'pindo/module/utils/file_downloader'
-require 'pindo/module/build/git_repo_helper'
+require 'pindo/module/utils/git_repo_helper'
 
 module Pindo
 

data/lib/pindo/module/android/android_project_helper.rb

@@ -1,8 +1,96 @@
+require "fileutils"
+require "pathname"
+
 module Pindo
   class AndroidProjectHelper
     class << self
 
 
+      # 确保导出的 Android 工程 `unityLibrary/libs` 里物理存在 Firebase Unity AAR（firebase-*-unity-*.aar）。
+      #
+      # 某些 Unity 工程会通过 EDM4U 将 Firebase Unity AAR 解析到 `Assets/GeneratedLocalRepo/**/m2repository`，
+      # 并在导出工程中使用本地 maven repo 方式引用它们，导致 `unityLibrary/libs` 为空。
+      # 当下游流程只携带“导出目录”时，这会表现为 Firebase AAR “缺失”。
+      #
+      # 本方法会从以下来源收集 firebase-*-unity-*.aar 并复制到导出工程：
+      # - Unity 工程的 `ProjectSettings/AndroidResolverDependencies.xml`（优先）
+      # - `Assets/GeneratedLocalRepo/**/m2repository/com/google/firebase/**/firebase-*-unity-*.aar`（兜底扫描）
+      #
+      # @return [Array<String>] 实际拷贝/确认存在的文件名列表
+      def ensure_export_has_firebase_unity_aars!(unity_root_path:, export_path:)
+        raise ArgumentError, "unity_root_path 不能为空" if unity_root_path.to_s.empty?
+        raise ArgumentError, "export_path 不能为空" if export_path.to_s.empty?
+        raise ArgumentError, "Unity 工程目录不存在: #{unity_root_path}" unless File.directory?(unity_root_path)
+        raise ArgumentError, "导出目录不存在: #{export_path}" unless File.directory?(export_path)
+
+        libs_dir = File.join(export_path, "unityLibrary", "libs")
+        FileUtils.mkdir_p(libs_dir)
+
+        # 若导出工程已包含所需的 firebase-*-unity-*.aar，则无需再从 Unity 工程侧反查来源（含 GeneratedLocalRepo）。
+        already = Dir.glob(File.join(libs_dir, "firebase-*-unity-*.aar")).select { |p| File.file?(p) }
+        return already.map { |p| File.basename(p) }.uniq unless already.empty?
+
+        resolver_xml = File.join(unity_root_path, "ProjectSettings", "AndroidResolverDependencies.xml")
+
+        candidates = []
+        if File.file?(resolver_xml)
+          begin
+            require "rexml/document"
+            doc = REXML::Document.new(File.read(resolver_xml))
+            doc.elements.each("dependencies/files/file") do |e|
+              rel = e.text.to_s.strip
+              next if rel.empty?
+              next unless rel.end_with?(".aar")
+              next unless rel.match?(/firebase-.*-unity-.*\.aar\z/i)
+
+              abs = Pathname.new(rel).absolute? ? rel : File.join(unity_root_path, rel)
+              candidates << abs
+            end
+          rescue StandardError => e
+            raise Informative, "解析 AndroidResolverDependencies.xml 失败: #{e.message}\n请在 Unity 中执行 EDM4U Force Resolve 后重试。"
+          end
+        end
+
+        if candidates.empty?
+          local_repo = File.join(unity_root_path, "Assets", "GeneratedLocalRepo")
+          if File.directory?(local_repo)
+            glob = File.join(local_repo, "**", "m2repository", "com", "google", "firebase", "**", "firebase-*-unity-*.aar")
+            candidates.concat(Dir.glob(glob))
+          end
+        end
+
+        candidates.uniq!
+        existing = candidates.select { |p| File.file?(p) }
+
+        if existing.empty?
+          raise Informative, <<~MSG
+            Firebase Unity AAR 依赖拷贝失败：未找到 firebase-*-unity-*.aar
+            Unity 工程: #{unity_root_path}
+            导出目录: #{export_path}
+            期望来源:
+            - #{resolver_xml}
+            - Assets/GeneratedLocalRepo/**/m2repository/com/google/firebase/**/firebase-*-unity-*.aar
+
+            请在 Unity 中执行：Assets → External Dependency Manager → Android Resolver → Force Resolve
+            然后重新导出再构建。
+          MSG
+        end
+
+        copied = []
+        existing.each do |src|
+          dst = File.join(libs_dir, File.basename(src))
+          if File.file?(dst) && File.size(dst) == File.size(src)
+            copied << File.basename(dst)
+            next
+          end
+
+          FileUtils.cp(src, dst)
+          copied << File.basename(dst)
+        end
+
+        copied.uniq
+      end
+
       def unity_android_project?(project_path)
         # 检查 unityLibrary 模块是否存在
         unity_library_path = File.join(project_path, "unityLibrary")

data/lib/pindo/module/android/gradle_helper.rb

@@ -205,7 +205,9 @@ module Pindo
         end
 
         # 生成 Wrapper
-        generate_gradle_wrapper(gradle_dir, gradle_version)
+        ok = generate_gradle_wrapper(gradle_dir, gradle_version)
+        ensure_gradlew_runnable!(gradle_dir)
+        ok
       end
 
       # 解析gradle版本
@@ -244,7 +246,30 @@ module Pindo
         end
 
         # 生成 Wrapper
-        generate_gradle_wrapper(gradle_dir, gradle_version)
+        ok = generate_gradle_wrapper(gradle_dir, gradle_version)
+        ensure_gradlew_runnable!(gradle_dir)
+        ok
+      end
+
+      # 确保工程根目录下 gradlew 可被当前环境执行：补齐执行位；在 macOS 上尝试移除
+      # com.apple.quarantine（无该属性时 xattr 失败可忽略）。用于避免
+      # 「bad interpreter: Operation not permitted」类错误，无用户交互。
+      def ensure_gradlew_runnable!(gradle_dir)
+        return if gradle_dir.nil? || gradle_dir.to_s.empty?
+
+        gradlew = File.join(gradle_dir, "gradlew")
+        return unless File.file?(gradlew)
+
+        begin
+          st = File.stat(gradlew)
+          File.chmod(st.mode | 0o111, gradlew)
+        rescue StandardError
+          # 只读卷等场景下忽略
+        end
+
+        return unless RUBY_PLATFORM.match?(/darwin/i)
+
+        system("xattr", "-d", "com.apple.quarantine", gradlew, out: File::NULL, err: File::NULL)
       end
 
       # =================== 私有辅助方法 ===================

data/lib/pindo/module/android/keystore_helper.rb

@@ -122,14 +122,34 @@ module Pindo
         @pindo_managed_signing_paths = []
       end
 
+      # 打包结束后恢复本次被修改的 Gradle 签名配置（仅恢复被本次任务改动过的文件）
+      def restore_managed_signing_config!
+        backups = @pindo_managed_gradle_backups || {}
+        backups.each do |path, original_content|
+          next if path.nil? || path.to_s.empty?
+          next unless original_content.is_a?(String)
+          next unless File.exist?(path)
+
+          File.write(path, original_content)
+        end
+      ensure
+        @pindo_managed_gradle_backups = {}
+      end
+
+      # 清理本次写入到进程 ENV 的签名变量（避免后续任务误继承）
+      def cleanup_managed_signing_env!
+        keys = @pindo_managed_env_keys || []
+        keys.each { |k| ENV.delete(k.to_s) if k }
+      ensure
+        @pindo_managed_env_keys = []
+      end
+
       # 将签名配置应用到 Android 工程
       #
       # 默认（与工程手写的 RELEASE_* 约定一致）：只拉取 JPS、拷贝 jks 到项目 signing/，并设置当前进程
       # RELEASE_KEYSTORE_PATH / RELEASE_KEYSTORE_PASSWORD / RELEASE_KEY_ALIAS / RELEASE_KEY_PASSWORD，不修改 build.gradle。
       # RELEASE_KEYSTORE_PATH 使用 jks 的绝对路径，便于 app 子模块内 `file(System.getenv(...))` 引用。
       #
-      # 若需恢复自动改写 signingConfigs，设置环境变量：PINDO_INJECT_ANDROID_SIGNING_GRADLE=1
-      #
       # @param project_dir [String] 项目目录
       # @param build_type [String] 构建类型 "debug" 或 "release"
       # @return [Boolean] 是否成功
@@ -139,6 +159,8 @@ module Pindo
         raise ArgumentError, "bundle_id 不能为空" if bundle_id.blank?
 
         reset_managed_signing_paths!
+        reset_managed_gradle_backups!
+        reset_managed_env_keys!
 
         main_module = Pindo::AndroidProjectHelper.get_main_module(project_dir)
         unless main_module
@@ -170,19 +192,16 @@ module Pindo
           raise "JPS keystore 未拷贝到工程 signing/（无法解析路径），Gradle 将回退到 build.gradle 中的本地 jks；请检查 JPS 证书是否下载成功"
         end
 
-        abs_keystore = File.expand_path(File.join(project_dir, rel_plain))
-
-        inject_gradle = Pindo::Options::GlobalOptionsState.instance[:injectsigning]
-        if inject_gradle
-          if gradle_file.end_with?(".kts")
-            ensure_keystore_config_kts(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
-          else
-            ensure_keystore_config_groovy(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
-          end
-          export_jps_release_signing_env!(cfg, keystore_path_for_env: rel_plain)
+        if gradle_file.end_with?(".kts")
+          ensure_keystore_config_kts(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
         else
-          export_jps_release_signing_env!(cfg, keystore_path_for_env: abs_keystore)
+          ensure_keystore_config_groovy(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
         end
+        # 注意：部分 Unity 导出工程/多模块工程的 Gradle rootProject 目录可能不是 project_dir，
+        # 相对路径（如 signing/xxx.jks）会被解析到错误的模块目录下（如 launcher/signing/...）。
+        # 这里改为导出绝对路径，确保与 keystore 创建/拷贝目录保持一致。
+        keystore_abs = File.expand_path(File.join(project_dir, rel_plain))
+        export_jps_release_signing_env!(cfg, keystore_path_for_env: keystore_abs)
         true
       end
 
@@ -244,6 +263,14 @@ module Pindo
         @pindo_managed_signing_paths = []
       end
 
+      def reset_managed_gradle_backups!
+        @pindo_managed_gradle_backups = {}
+      end
+
+      def reset_managed_env_keys!
+        @pindo_managed_env_keys = []
+      end
+
       def register_managed_signing_path!(path)
         return if path.nil? || path.to_s.empty?
 
@@ -251,6 +278,23 @@ module Pindo
         @pindo_managed_signing_paths << path
       end
 
+      def register_managed_gradle_backup!(path, original_content)
+        return if path.nil? || path.to_s.empty?
+        return unless original_content.is_a?(String)
+
+        @pindo_managed_gradle_backups ||= {}
+        # 同一文件只备份一次：第一次写入前的内容即为“原始内容”
+        @pindo_managed_gradle_backups[path] ||= original_content
+      end
+
+      def register_managed_env_key!(key)
+        return if key.nil? || key.to_s.empty?
+
+        @pindo_managed_env_keys ||= []
+        @pindo_managed_env_keys << key.to_s
+        @pindo_managed_env_keys.uniq!
+      end
+
       # 将 JPS 返回的路径/口令/别名写入当前进程环境变量，供 Gradle / bundletool 子进程继承（与 build.gradle 中 RELEASE_* 名称一致）
       def export_jps_release_signing_env!(cfg, keystore_path_for_env:)
         return unless cfg.is_a?(Hash)
@@ -258,6 +302,7 @@ module Pindo
         if keystore_path_for_env && !keystore_path_for_env.to_s.empty?
           ENV[ENV_RELEASE_KEYSTORE_PATH] =
             keystore_path_for_env
+          register_managed_env_key!(ENV_RELEASE_KEYSTORE_PATH)
         end
 
         sp = cfg["storePassword"]
@@ -270,6 +315,10 @@ module Pindo
         ENV[ENV_RELEASE_KEYSTORE_PASSWORD] = sp_plain.to_s if sp_plain && !sp_plain.to_s.empty?
         ENV[ENV_RELEASE_KEY_PASSWORD] = kp_plain.to_s if kp_plain && !kp_plain.to_s.empty?
         ENV[ENV_RELEASE_KEY_ALIAS] = ka.to_s if ka && !ka.to_s.empty?
+
+        register_managed_env_key!(ENV_RELEASE_KEYSTORE_PASSWORD) if sp_plain && !sp_plain.to_s.empty?
+        register_managed_env_key!(ENV_RELEASE_KEY_PASSWORD) if kp_plain && !kp_plain.to_s.empty?
+        register_managed_env_key!(ENV_RELEASE_KEY_ALIAS) if ka && !ka.to_s.empty?
       end
 
       # Groovy：解析 storePassword/keyPassword（支持 System.getenv、可选 ?: 回退、或历史明文）
@@ -517,6 +566,7 @@ module Pindo
         if content == original_content
           puts "  ✓ build.gradle 无需修改"
         else
+          register_managed_gradle_backup!(gradle_file, original_content)
           File.write(gradle_file, content)
           puts "  ✓ build.gradle 已更新"
         end
@@ -571,6 +621,7 @@ module Pindo
         if content == original_content
           puts "  ✓ build.gradle.kts 无需修改"
         else
+          register_managed_gradle_backup!(gradle_file, original_content)
           File.write(gradle_file, content)
           puts "  ✓ build.gradle.kts 已更新"
         end
@@ -1285,34 +1336,52 @@ module Pindo
 
       # =================== 写入 keystore 配置的辅助方法 ===================
 
-      # 生成签名配置代码块（Groovy）——与工程约定：RELEASE_* + ?: 本地回退（明文仅回退串，来自 JPS 的敏感值走本次进程 ENV）
+      # 生成签名配置代码块（Groovy）
+      # 注意：签名信息只允许从环境变量读取，严禁在 build.gradle 中写入任何明文（包括回退密码/alias/路径）。
       def generate_signing_config_groovy(config_name, pindo_config)
-        rel_fb = escape_gradle_double_quoted(signing_keystore_fallback_relative(pindo_config))
-        alias_fb = escape_gradle_double_quoted(pindo_config["keyAlias"])
-
         <<~GROOVY
           #{config_name} {
-                  def keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}") ?: "#{rel_fb}"
-                  storeFile rootProject.file(keystorePath)
-                  storePassword System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}") ?: "123456"
-                  keyAlias System.getenv("#{ENV_RELEASE_KEY_ALIAS}") ?: "#{alias_fb}"
-                  keyPassword System.getenv("#{ENV_RELEASE_KEY_PASSWORD}") ?: "123456"
+                  def signingEnvVars = ["#{ENV_RELEASE_KEYSTORE_PATH}", "#{ENV_RELEASE_KEYSTORE_PASSWORD}", "#{ENV_RELEASE_KEY_ALIAS}", "#{ENV_RELEASE_KEY_PASSWORD}"]
+                  def missing = signingEnvVars.findAll { !System.getenv(it) }
+                  if (!missing.isEmpty()) {
+                      throw new GradleException("Missing required environment variables for release signing: ${missing.join(', ')}")
+                  }
+                  def keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}")
+                  def keystoreFile = rootProject.file(keystorePath)
+                  if (!keystoreFile.exists()) {
+                      throw new GradleException("Keystore file not found: ${keystoreFile.absolutePath}")
+                  }
+                  storeFile keystoreFile
+                  storePassword System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}")
+                  keyAlias System.getenv("#{ENV_RELEASE_KEY_ALIAS}")
+                  keyPassword System.getenv("#{ENV_RELEASE_KEY_PASSWORD}")
               }
         GROOVY
       end
 
       # 生成签名配置代码块（Kotlin DSL）
       def generate_signing_config_kts(config_name, pindo_config)
-        rel_fb = escape_gradle_double_quoted(signing_keystore_fallback_relative(pindo_config))
-        alias_fb = escape_gradle_double_quoted(pindo_config["keyAlias"])
-
         <<~KOTLIN
           create("#{config_name}") {
-                  val keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}") ?: "#{rel_fb}"
-                  storeFile = rootProject.file(keystorePath)
-                  storePassword = System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}") ?: "123456"
-                  keyAlias = System.getenv("#{ENV_RELEASE_KEY_ALIAS}") ?: "#{alias_fb}"
-                  keyPassword = System.getenv("#{ENV_RELEASE_KEY_PASSWORD}") ?: "123456"
+                  val signingEnvVars = listOf(
+                      "#{ENV_RELEASE_KEYSTORE_PATH}",
+                      "#{ENV_RELEASE_KEYSTORE_PASSWORD}",
+                      "#{ENV_RELEASE_KEY_ALIAS}",
+                      "#{ENV_RELEASE_KEY_PASSWORD}",
+                  )
+                  val missing = signingEnvVars.filter { System.getenv(it).isNullOrBlank() }
+                  if (missing.isNotEmpty()) {
+                      throw GradleException("Missing required environment variables for release signing: ${missing.joinToString(\", \")}")
+                  }
+                  val keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}")
+                  val keystoreFile = rootProject.file(keystorePath)
+                  if (!keystoreFile.exists()) {
+                      throw GradleException("Keystore file not found: ${keystoreFile.absolutePath}")
+                  }
+                  storeFile = keystoreFile
+                  storePassword = System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}")
+                  keyAlias = System.getenv("#{ENV_RELEASE_KEY_ALIAS}")
+                  keyPassword = System.getenv("#{ENV_RELEASE_KEY_PASSWORD}")
               }
         KOTLIN
       end