diff --git a/sdk-update/src/main/java/com/xuqm/sdk/update/UpdateSDK.kt b/sdk-update/src/main/java/com/xuqm/sdk/update/UpdateSDK.kt
index 453f2db..bc2f39d 100644
--- a/sdk-update/src/main/java/com/xuqm/sdk/update/UpdateSDK.kt
+++ b/sdk-update/src/main/java/com/xuqm/sdk/update/UpdateSDK.kt
@@ -20,6 +20,32 @@ object UpdateSDK {
 
     private val api: UpdateApi get() = ApiClient.create(UpdateApi::class.java, ServiceEndpointRegistry.updateBaseUrl)
 
+    /**
+     * 外部设置的 userId，优先于 [XuqmSDK.currentLoginSession] 中的 userId。
+     * 适用于 App 有自己的登录体系，不走 XuqmSDK.login，但仍需灰度发布按用户筛选的场景。
+     */
+    private var externalUserId: String? = null
+
+    /**
+     * 设置 userId，用于检查更新时的灰度发布筛选。
+     *
+     * 设置后，[checkAppUpdate] 会优先使用此 userId，而不是从 [XuqmSDK.currentLoginSession] 获取。
+     * 适用于 App 有自己的用户体系，不通过 [XuqmSDK.login] 登录的场景。
+     *
+     * @param userId 用户标识，传 null 则清除，恢复使用 XuqmSDK 登录会话中的 userId
+     */
+    fun setUserId(userId: String?) {
+        externalUserId = userId?.takeIf { it.isNotBlank() }
+    }
+
+    /**
+     * 获取当前生效的 userId。
+     * 优先级：[externalUserId] > [XuqmSDK.currentLoginSession]?.userId
+     */
+    private fun resolveUserId(): String? {
+        return externalUserId ?: XuqmSDK.currentLoginSession?.userId
+    }
+
     private fun normalizeDownloadUrl(rawUrl: String?): String? {
         if (rawUrl.isNullOrBlank()) return rawUrl
 
@@ -123,7 +149,8 @@ object UpdateSDK {
      *   - `false`（默认，静默检查）：用户已忽略的版本不再弹窗，适合启动时后台检查。
      *   - `true`（主动检查）：忽略记录不生效，始终弹出更新对话框；无更新时由调用方显示提示。
      *
-     * userId 通过 [XuqmSDK.login] 设置会话后自动传递，无需外部覆盖。
+     * userId 优先使用 [setUserId] 设置的值，其次从 [XuqmSDK.currentLoginSession] 获取。
+     * 灰度发布需要 userId 来判断用户是否命中灰度范围。
      *
      * 返回的 [UpdateInfo.alreadyDownloaded] 为 true 时，可直接调用 [installDownloadedApk] 安装，
      * 无需再次调用 [downloadAndInstall]。
@@ -137,7 +164,7 @@ object UpdateSDK {
             @Suppress("DEPRECATION")
             packageInfo.versionCode
         }
-        val userId = XuqmSDK.currentLoginSession?.userId
+        val userId = resolveUserId()
         runCatching {
             api.checkUpdate(XuqmSDK.appKey, "ANDROID", versionCode, userId).data?.let { info ->
                 val normalized = info.copy(downloadUrl = normalizeDownloadUrl(info.downloadUrl) ?: info.downloadUrl)