From 75f7ee9f35cdbc6852cf572e17602c9f363c755a Mon Sep 17 00:00:00 2001
From: Shine <i@nowtime.cc>
Date: Tue, 26 May 2026 22:02:58 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=94=AF=E6=8C=81=E9=80=9A=E8=BF=87?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E7=8B=AC=E7=AB=8B=E6=8E=A7=E5=88=B6=20JS/CSS?=
 =?UTF-8?q?=20=E8=B5=84=E6=BA=90=E7=BC=93=E5=AD=98=E7=89=88=E6=9C=AC?=
 =?UTF-8?q?=E5=8F=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 `admin.assets_version` 配置项（对应 `ADMIN_ASSETS_VERSION` 环境变量），
允许用户自定义附加在 JS/CSS URL 上的缓存破坏版本参数，不再强制跟随框架版本。
设为空值时不添加任何版本查询参数。
---
 README.md                     |  1 +
 config/admin.php              | 12 ++++++++++++
 src/Console/stubs/config.stub | 12 ++++++++++++
 src/Layout/Asset.php          |  8 +++++++-
 4 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ddea3147b..092b03c57 100755
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@
 
 > 更多功能正在持续开发... 欢迎交流评论
 
+- 支持通过 `admin.assets_version` 配置项（或 `ADMIN_ASSETS_VERSION` 环境变量）自定义 JS/CSS 缓存破坏版本号，不再强制跟随框架版本
 - [2025/08/05 增强对枚举字段的渲染支持](https://github.com/PrintNow/dcat-admin/pull/5)
 - [@deflinhec : 修正 Grid 以 LazyRenderable 呈現時Group Filter 沒有正確篩選](https://github.com/PrintNow/dcat-admin/commit/4390a8f494c20910828e7c93513d13032f0d01dd)
 - [新增 highlightjs 类以支持代码块高亮显示](https://github.com/PrintNow/dcat-admin/commit/52050882eea475b9d3863ace98048404f7d320b7)
diff --git a/config/admin.php b/config/admin.php
index d805463ee..d0471e3c0 100755
--- a/config/admin.php
+++ b/config/admin.php
@@ -106,6 +106,18 @@
    */
     'assets_server' => env('ADMIN_ASSETS_SERVER'),
 
+    /*
+    |--------------------------------------------------------------------------
+    | Assets version
+    |--------------------------------------------------------------------------
+    |
+    | The version string appended to JS/CSS URLs as a cache-busting query
+    | parameter (e.g. `?v1.0.0`). Defaults to the framework version. Set to
+    | null/empty to disable the version query entirely.
+    |
+    */
+    'assets_version' => env('ADMIN_ASSETS_VERSION'),
+
     /**
      * @deprecated 不再建议使用此配置。如果你使用了反向代理，配置好 `app/Http/Middleware/TrustProxies.php` 中的 $proxies 属性，
      *             页面就会自动使用 https 协议。未来将完全移除此配置。
diff --git a/src/Console/stubs/config.stub b/src/Console/stubs/config.stub
index 1ba664b55..974e6706c 100644
--- a/src/Console/stubs/config.stub
+++ b/src/Console/stubs/config.stub
@@ -104,6 +104,18 @@ return [
    */
     'assets_server' => env('ADMIN_ASSETS_SERVER'),
 
+    /*
+    |--------------------------------------------------------------------------
+    | Assets version
+    |--------------------------------------------------------------------------
+    |
+    | The version string appended to JS/CSS URLs as a cache-busting query
+    | parameter (e.g. `?v1.0.0`). Defaults to the framework version. Set to
+    | null/empty to disable the version query entirely.
+    |
+    */
+    'assets_version' => env('ADMIN_ASSETS_VERSION'),
+
     /*
     |--------------------------------------------------------------------------
     | Access via `https`
diff --git a/src/Layout/Asset.php b/src/Layout/Asset.php
index cdfbb167c..fa24e97e5 100644
--- a/src/Layout/Asset.php
+++ b/src/Layout/Asset.php
@@ -689,7 +689,13 @@ public function withVersionQuery($url)
             $url .= '?';
         }
 
-        $ver = 'v'.Admin::VERSION;
+        $assetsVersion = config('admin.assets_version', Admin::VERSION);
+
+        if (! $assetsVersion) {
+            return rtrim($url, '?');
+        }
+
+        $ver = 'v'.$assetsVersion;
 
         return Str::endsWith($url, '?') ? $url.$ver : $url.'&'.$ver;
     }