resources.GetRemote

{{ $url := "https://example.org/images/a.jpg" }}
{{ with resources.GetRemote $url }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ else }}
  {{ errorf "無法取得遠端資源 %q" $url }}
{{ end }}

選項

resources.GetRemote 函式可以接受一個可選的選項映射 (map)。

{{ $url := "https://example.org/api" }}
{{ $opts := dict
  "headers" (dict "Authorization" "Bearer abcd")
}}
{{ $resource := resources.GetRemote $url $opts }}

如果需要為相同的標頭鍵提供多個值，使用切片 (slice)：

{{ $url := "https://example.org/api" }}
{{ $opts := dict
  "headers" (dict "X-List" (slice "a" "b" "c"))
}}
{{ $resource := resources.GetRemote $url $opts }}

你也可以變更請求方法並設置請求主體：

{{ $url := "https://example.org/api" }}
{{ $opts := dict
  "method" "post"
  "body" `{"complete": true}` 
  "headers" (dict  "Content-Type" "application/json")
}}
{{ $resource := resources.GetRemote $url $opts }}

遠端資料

當取得遠端資料時，使用 transform.Unmarshal 函式來反序列化回應。

{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    {{ $data = . | transform.Unmarshal }}
  {{ end }}
{{ else }}
  {{ errorf "無法取得遠端資源 %q" $url }}
{{ end }}

錯誤處理

resources.GetRemote 函式返回的資源上的 Err 方法，當 HTTP 請求失敗時會回傳一個錯誤訊息，否則回傳 nil。如果你未自行處理錯誤，Hugo 會使建置失敗。

{{ $url := "https://broken-example.org/images/a.jpg" }}
{{ with resources.GetRemote $url }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ else }}
  {{ errorf "無法取得遠端資源 %q" $url }}
{{ end }}

若要將錯誤記錄為警告而非錯誤：

{{ $url := "https://broken-example.org/images/a.jpg" }}
{{ with resources.GetRemote $url }}
  {{ with .Err }}
    {{ warnf "%s" . }}
  {{ else }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ else }}
  {{ errorf "無法取得遠端資源 %q" $url }}
{{ end }}

HTTP 回應

resources.GetRemote 函式返回的資源上的 Data 方法提供有關 HTTP 回應的資訊。

{{ $url := "https://example.org/images/a.jpg" }}
{{ with resources.GetRemote $url }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    {{ with .Data }}
      {{ .ContentLength }} → 42764
      {{ .ContentType }} → image/jpeg
      {{ .Status }} → 200 OK
      {{ .StatusCode }} → 200
      {{ .TransferEncoding }} → []
    {{ end }}
  {{ end }}
{{ else }}
  {{ errorf "無法取得遠端資源 %q" $url }}
{{ end }}
ContentLength
(int) 資源大小（位元組）。
ContentType
(string) 資源的內容類型。
Status
(string) HTTP 狀態訊息。
StatusCode
(int) HTTP 狀態碼。
TransferEncoding
(string) 傳輸編碼。

快取

從 resources.GetRemote 返回的資源會快取到磁碟。詳情請參閱配置檔案快取。

預設情況下，Hugo 根據傳遞給函式的參數（URL 和選項映射）來派生快取鍵。

可以透過在選項映射中設置 key 來覆寫快取鍵。此方法允許更靈活地控制 Hugo 獲取遠端資源的頻率。

{{ $url := "https://example.org/images/a.jpg" }}
{{ $cacheKey := print $url (now.Format "2006-01-02") }}
{{ $resource := resources.GetRemote $url (dict "key" $cacheKey) }}

安全性

為防止惡意行為，resources.GetRemote 函式會檢查伺服器回應，包括：

  • 回應標頭中的 Content-Type
  • 文件副檔名（若有）
  • 資源內容

若 Hugo 無法將媒體類型解析為其允許清單中的條目，函式將拋出錯誤：

ERROR error calling resources.GetRemote: failed to resolve media type...

例如，若嘗試下載可執行檔案，你會看到上述錯誤。

儘管允許清單包含常見媒體類型的條目，你可能會遇到 Hugo 無法解析某些已知安全文件的情況。此時，請編輯網站配置，將媒體類型新增至允許清單。例如：

hugo.
      
security:
  http:
    mediaTypes:
    - ^image/avif$
    - ^application/vnd\.api\+json$

[security]
  [security.http]
    mediaTypes = ['^image/avif$', '^application/vnd\.api\+json$']

{
   "security": {
      "http": {
         "mediaTypes": [
            "^image/avif$",
            "^application/vnd\\.api\\+json$"
         ]
      }
   }
}

請注意，上述條目為：

  • 允許清單的補充，而非取代
  • 一個正規表示式的陣列
resources.Match resources.GetMatch