全部產品
Search

搜尋本產品

    CDN：自訂Cache Key

    文件中心

    CDN：自訂Cache Key

    更新時間：Jun 25, 2026

    配置自訂緩衝鍵（Cache Key），開發人員可以根據HTTP請求的不同部分（例如URI、請求參數、HTTP要求標頭或自訂變數等）制定規則來產生Cache Key，將訪問同一個檔案的一類請求轉化為統一的Cache Key，提高快取命中率，降低回源率，減少請求的回應時間和頻寬消耗。

    功能對比與選擇

    • 自訂Cache Key與 忽略參數 存在衝突 ：開啟忽略參數後，節點會去除URL中?之後的參數，導致自訂Cache Key中的請求參數配置失效。使用自訂Cache Key前，請關閉忽略參數。

    • 自訂Cache Key功能更全面，可替代忽略參數緩衝鍵配置，推薦優先使用。配置對比：

      情境

      忽略參數

      自訂Cache Key

      在緩衝鍵中忽略所有請求參數

      忽略參數設定為是，保留指定參數留空

      添加一條請求參數處理策略：

      • 操作方式：保留

      • 參數名：設為任意不存在的參數名，例如 example-argument

      在緩衝鍵中僅保留請求參數key1

      忽略參數設定為是，保留指定參數設定為key1

      添加一條請求參數處理策略：

      • 操作方式：保留

      • 參數名：key1

      在緩衝鍵中僅刪除請求參數key1

      刪除指定參數設定為key1

      添加一條請求參數處理策略：

      • 操作方式：刪除

      • 參數名：key1

    • 回源參數改寫：自訂Cache Key功能不修改回源URL，僅修改請求的緩衝標識，回源請求與用戶端請求內容一致。如果需要改寫回源URL攜帶的請求參數，請使用重寫回源參數。

    • 緩衝重新整理：配置自訂 Cache Key 後，按URL提交重新整理任務可能無法正確匹配緩衝內容，請提交經過自訂Cache Key功能處理後的緩衝鍵作為重新整理對象。

    使用情境

    重要

    自訂Cache Key功能不會修改回源的URL，僅會修改請求的緩衝標識，回源的請求和用戶端發起的請求內容保持一致。

    Cache Key是一個檔案在CDN節點上緩衝時唯一的身份ID，每個在CDN節點上緩衝的檔案都對應一個Cache Key。檔案的Cache Key預設為用戶端請求的URL（帶參數）。

    情境一

    客戶不同請求的URL中含有複雜的參數，因此即使多個請求訪問的是同一個檔案，但由於URL參數不同，CDN節點會視為請求不同檔案而將不同請求緩衝成多個檔案，造成回源的請求增加。圖一

    可通過自訂Cache Key規則將同一類請求的Cache Key統一，降低回源率。圖二

    情境二

    用戶端請求的URL一樣時，CDN將視為請求同一個檔案。但實際上請求的Http Header中攜帶了client欄位區分了用戶端系統，希望請求不同檔案。情境一

    此時可通過自訂Cache Key將client欄位的值拼接至Cache Key，兩個請求即可識別為2個不同的Cache Key。情境二

    重要

    功能配置在引用規則引擎上的規則條件配置時，配置的執行順序不是按照配置的優先順序順序執行，而是會按照配置關聯的規則條件的優先順序順序來執行。

    操作步驟

    1. 登入CDN控制台。

    2. 在左側導覽列，單擊域名管理。

    3. 在域名管理頁面，找到目標網域名稱，單擊操作列的管理。

    4. 在指定網域名稱的左側導覽列，單擊缓存配置。

    5. 在自訂Cachekey頁簽下，單擊配置，配置Cache Key。

      參數類型

      操作說明

      規則條件

      規則條件能夠對使用者請求中攜帶的各種參數資訊進行識別，以此來決定某個配置是否對該請求生效。

      重要

      引用規則條件時，按所關聯規則條件的優先順序匹配，而非按功能自身的配置順序匹配。

      • 不使用：不使用規則條件。

      • 若需新增或編輯規則條件，請在規則引擎中進行管理。

      URI

      當用戶端請求的URI與配置中的源URI相匹配時，系統會用配置中的目標URI替換源URI，來產生Cache Key。則使用配置中的目標URI替換源URI來拼接Cache Key。

      支援配置多個URI替換策略。若存在多條策略，則按照從上到下的順序依次進行匹配。一旦匹配到某個源URI，系統將使用該策略對應的目標URI執行替換操作，並停止與後續策略的匹配。

      • 源URI：以正斜線（/）開頭的URI，不含http://頭及網域名稱。支援PCRERegex。

      • 目標URI：以正斜線（/）開頭的URI，不含http://頭及網域名稱。

      請求參數

      操作的對象是使用者發起的原始請求URL中攜帶的參數，可以對參數進行新增、刪除、修改、僅保留操作，操作後的結果將會拼接到Cache Key中。支援設定多個操作，存在多個操作的情況下，將會從上到下按順序逐個執行。

      • 新增：將新增的請求參數拼接到Cache Key中。例如：原始URL為http://image.example.com/cat.jpg，新增一個請求參數type=jpg，則Cache Key為http://image.example.com/cat.jpg?type=jpg。

      • 刪除：在產生Cache Key的時候刪除原始請求URL中的指定參數。例如：原始URL為 http://image.example.com/cat.jpg?type=jpg，刪除參數type，則Cache Key為http://image.example.com/cat.jpg。

      • 修改：在產生Cache Key的時候修改原始請求URL中的指定參數。例如：原始URL為 http://image.example.com/cat.jpg?type=jpg，修改參數type=png，則Cache Key為。

      • 僅保留：在產生Cache Key的時候僅保留原始請求URL中的指定參數。例如：原始URL為http://image.example.com/cat.jpg?type=jpg&path=image，保留參數type，則Cache Key為http://image.example.com/cat.jpg?type=jpg。

      HTTP Header

      將用戶端原始請求中攜帶的指定HTTP Header的值拼接到Cache Key中。支援配置多個HTTP Header名稱（多個 HTTP Header 名稱之間用空格分隔），效果是每個HTTP Header的值將會按順序拼接到Cache Key中。

      例如：原始URL為 http://image.example.com/cat.jpg，用戶端請求攜帶了一個HTTP Header（path:image）；如果HTTP Header中設定了path這個要求標頭，則Cache Key為http://image.example.com/cat.jpgimage。

      自訂變數

      可以使用Regex來匹配用戶端原始請求中攜帶的指定請求參數的值、指定HTTP Header的值、指定Cookie參數的值、指定的URI，Regex匹配命中時，將對應的值拼接到Cache Key中。具體使用請參見配置樣本。

    6. 單擊確定。

    配置樣本

    URI

    用戶端的請求http://aliyundoc.com/a/b/image.jpg和http://aliyundoc.com/a/b/c/image.jpg 將視為請求同一個檔案，該檔案的Cache Key為http://aliyundoc.com/c/image.jpg。URI改寫規則配置樣本：將源URI /a/b 改寫為目標URI /c，將源URI /a/b/c 改寫為目標URI /c。單擊+ 添加源URI可新增改寫規則，單擊刪除可移除已有規則。

    請求參數

    用戶端的請求http://aliyundoc.com/a/b/image.jpg?delete_par=1&modify_par=1 將按規則添加add_par=1，刪除delete_par，將modify_par的值修改為2，最終轉化為http://aliyundoc.com/a/b/image.jpg?modify_par=2&add_par=1。

    重要

    請求參數中，如對同一個變數同時進行了多個操作，則各種操作的生效優先順序：新增>刪除>保留>修改。

    刪除操作僅支援輸入單個參數名，如需刪除多個參數，可單擊添加參數操作增補多條刪除操作。

    HTTP Header

    用戶端請求的HTTP Header的User-Agent和Accept-Language的值將被拼接到Cache Key中。例如請求http://aliyundoc.com/a/b/image.jpg中的User-Agent=Mozilla/5.0 (Linux; X11)，Accept-Language=en，則該請求的Cache Key為：http://aliyundoc.com/a/b/image.jpgMozilla/5.0(Linux;X11)en。在 HTTP HEADER 輸入框中填寫需要採集的要求標頭欄位，例如 User-Agent 和 Accept-Language。

    自訂變數

    樣本一

    變數名為language，來源為Request Header，來源欄位名為Accept-Language，匹配規則為 ([%w]+),([%w]+)，Variant 運算式為$1aa。自訂變數配置樣本：變數名設定為 language，來源選擇 Request Header，來源欄位名填寫 Accept-Language，匹配規則填寫 ([%w]+),([%w]+)，Variant 運算式填寫 $1aa。

    用戶端的請求http://aliyundoc.com/a/b/image.jpg且攜帶HTTP要求標頭Accept-Language=en,ch ，則匹配規則將匹配到en賦值給Variant 運算式中的$1。Variant 運算式還將在末尾拼接上aa，得到enaa的變數並取別名為language，拼接在URL後方形成最終的Cache Key：http://aliyundoc.com/a/b/image.jpgenaa。

    說明

    Variant 運算式中的$n的含義是匹配規則中第n個括弧所匹配到的內容。例如樣本一中Accept-Language=en,ch，匹配規則為([%w]+),([%w]+)，則$1=en，$2=ch。

    樣本二

    變數名為expired，來源為Request Cookie，來源欄位名為a，匹配規則為[%w]+:(.*)，Variant 運算式為 $1。自訂變數配置樣本： - 變數名：expired - 來源：Request Cookie - 來源欄位名：a - 匹配規則：[%w]+:(.*) - Variant 運算式：$1

    用戶端的請求http://aliyundoc.com/a/b/image.jpg且攜帶Cookie a=expired_time:12635187，則匹配規則將匹配到12635187賦值給Variant 運算式中的$1並取別名為expired，拼接在URL後方形成最終的Cache Key：http://aliyundoc.com/a/b/image.jpg12635187。

    樣本三

    同時設定URI規則和自訂變數。

    URI：

    將所有URI符合/abc/.*/abc的請求都合并成 /abc。源URI為/abc/.*/abc，目標URI為/abc。

    自訂變數：

    變數名為testname，來源為Path，匹配規則為/abc/xyz/(.*)，Variant 運算式為$1。變數名：testname；來源：Path；匹配規則：/abc/xyz/(.*)；Variant 運算式：$1

    用戶端的請求URLhttp://aliyundoc.com/abc/xyz/abc/image.jpg，按URI的配置Cache Key將被合并成http://aliyundoc.com/abc/image.jpg， 然後根據自訂變數的配置該URL將會命中/abc/xyz/(.*)，此時$1將被賦值為abc並拼接到Cache Key中，形成最終的Cache Key：http://aliyundoc.com/abc/image.jpgabc，從而達到兩個規則群組合使用，實現更複雜的緩衝邏輯。

    如果沒有匹配到Cache Key的自訂變數，則Variant 運算式$1就不會被拼接到Cache Key中。

    樣本四

    同時設定規則條件和自訂變數，使來自Mobile端和PC端的請求產生不同的Cache Key。

    Mobile規則條件：

    User-Agent包含*Mobile*,*Android*,*iPhone*,*ipad*其中任意一個

    PC規則條件：

    User-Agent不包含*Mobile*,*Android*,*iPhone*,*ipad*其中任意一個

    Mobile自訂Cache Key：

    規則條件選擇Mobile，自訂變數的變數名為Mobile，來源為Path，匹配規則為/，Variant 運算式為+mobile。

    PC自訂Cache Key：

    規則條件選擇PC，自訂變數的變數名為PC，來源為Path，匹配規則為/，Variant 運算式為+pc。

    用戶端的請求URLhttp://aliyundoc.com/image.jpg，根據User-Agent的值，請求分別命中Mobile端和PC端的自訂Cache Key規則。Mobile端最終產生的Cache Key為：http://aliyundoc.com/image.jpg+mobile；PC端最終產生的Cache Key為：http://aliyundoc.com/image.jpg+pc。

    常見問題

    配置自訂 Cache Key 區分不同 Token 請求後仍命中緩衝且未回源怎麼辦？

    配置自訂 Cache Key 區分不同 Token 的請求後，仍出現命中緩衝且請求未回源的情況，請按以下步驟排查：

    1. 檢查配置：確認已將攜帶 Token 的 HTTP Header 加入自訂 Cache Key，或者將緩衝時間設定為 0 秒。

    2. 重新整理緩衝：配置修改後，需提交目錄重新整理以清除舊緩衝。URL 重新整理不支援萬用字元 *，建議使用目錄重新整理。

    3. 用戶端驗證：清除瀏覽器緩衝或重啟瀏覽器後重試，檢查回應標頭中的緩衝標識是否為 MISS，確認未命中 CDN 緩衝。

    4. 後端排查：若回應標頭顯示 MISS 但後端仍無日誌，需檢查後端負載平衡配置及網關日誌，確認請求是否到達來源站點。

    5. 許可權核查：若無法查詢詳細日誌，需確認當前帳號是否有該 CDN 網域名稱的系統管理權限，或通過主帳號申請 AliyunSupportFullAccess 許可權，提供 EagleID 由擁有網域名稱的帳號協助排查。

    配置自訂 Cache Key 區分移動端和 PC 端緩衝後測試未生效怎麼辦？

    配置自訂 Cache Key 區分 Mobile 和 PC 端緩衝後測試未生效，請按以下步驟排查：

    1. 檢查配置衝突：確認未開啟忽略參數功能。忽略參數會與自訂 Cache Key 衝突，導致配置不生效。

    2. 檢查配置完整性：確保 Mobile 和 PC 分別配置了自訂變數。Mobile 規則的Variant 運算式應設為 +mobile，PC 規則的Variant 運算式應設為 +pc。配置樣本見本文「樣本四」。

    3. 等待生效：配置提交後需等待 5～10 分鐘全網同步。

    4. 進一步排查：如以上步驟確認無誤仍未生效，建議提供測試返回的 EagleID 以便查詢 CDN 日誌進一步排查。

    未開啟 ESA 時是否可以使用自訂 Cache Key？

    可以。自訂 Cache Key 是 CDN 的基礎緩衝配置功能，無需開啟 ESA 即可使用。

    配置路徑：登入 CDN 控制台 > 網域名稱管理 > 單擊目標網域名稱的管理 > 左側導覽列選擇緩衝配置 > 在自訂 Cache Key 頁簽下單擊配置。

    重要

    若已開啟忽略參數功能，需先關閉，否則會導致自訂 Cache Key 中的請求參數配置失效。

    CDN 自訂 Cache Key 能否實現動態介面的緩衝效果？

    不能。CDN 主要用於靜態資源加速，無法實現動態介面的加速效果。自訂 Cache Key 用於最佳化靜態資源的緩衝策略（如統一 URL 參數、區分用戶端等），不適用於動態介面緩衝情境。如需動態內容加速，可使用。