外部圖片直接打開有圖，放進 Next.js 的 Image 元件卻報「hostname is not configured」。先抄下出錯的完整 src，再與 remotePatterns 一段一段核對。它不是只認域名：協定、主機、port、路徑與查詢字串，都可能讓同一張海報被拒絕。
以下採 Next.js 16 的預設 Image loader。先核專案版本及現有 next.config；若網站用了自訂 loader 或停用最佳化，請求路徑可能不同，不能直接用這份判斷當所有圖片功能的規則。
先找原圖 src，而不是只看最佳化網址
在錯誤訊息中找 Image 的 src，或從 Network 的圖片請求讀取 url 參數。看到 /_next/image?url=... 時，外層是 Next 的最佳化入口，裡面解碼後的 url 才是要拿來比對的外部圖片來源。
例如 https://media.example/account123/poster.png?v=2，可拆成協定 https、主機 media.example、空的非預設 port、路徑 /account123/poster.png，以及查詢字串 ?v=2。這是地址示例，正式設定要換成自己獲准使用的圖片主機與路徑。
留意實際值是否多了一個子域名，或路徑原本是 /account123/，來源卻回傳 /uploads/account123/。不要只看副檔名相同就判定符合。比對以完整 src 為準，不能把頁面所在域名或網址最後跳到哪裡，誤當輸入給 Image 的值。
只放行需要的主機與資料夾
假設這個網站只需要同一帳號資料夾、HTTPS、沒有查詢字串的圖片，可在設定裡寫成：
module.exports = {
images: {
remotePatterns: [{
protocol: 'https',
hostname: 'media.example',
port: '',
pathname: '/account123/**',
search: '',
}],
},
};這段是設定片段，應整合進原本的 images 物件，保留既有其他來源。專案若用 next.config.mjs 或 TypeScript 設定檔，沿用對應的匯出方式，不要另外放第二份互相衝突的設定。
pathname 中的 ** 可以配對末端多層路徑；它不是任意插在中間就能配所有字串。官方也說明單一星號與雙星號的用途不同。先用明確資料夾範圍，別把整個 hostname 或 pathname 都省略，只為了消除眼前的錯誤。
port 也要分清楚。圖片主機若使用特定連接埠，就按實際值設定；公開 HTTPS 的預設連接通常不會留下非預設 port。不要把開發服務的 port 複製到正式來源，也不要因兩個地址最後通往同一台機器，就認定匹配會把它們當成同一個主機名。
路徑的大小寫與階層同樣要保留。示例額外核對 /Assets/，因為不符合設定中的 /assets/ 而被拒絕；在 /assets/nested/ 放同一張自有圖片，則符合末端雙星號並取得圖片。這兩個結果幫你分清楚「允許多層子目錄」與「任意拼法都可用」。
search 空字串與沒寫，是兩個範圍
search: '' 表示來源不能帶查詢字串；因此一個本來可用的 poster.png，加了 ?v=2 後就可能不符合。若來源固定需要 ?v=2，可按文件指定該完整字串，不要以為空字串會忽略所有參數。
省略 search 則允許各種查詢參數，範圍更大。來源使用簽名或短期權杖時，先弄清楚它會產生哪些地址、哪些能被你的服務取得，再決定規則。不要把真實權杖貼進文章、公開截圖或錯誤回報。
使用 new URL('https://media.example/account123/**') 的寫法時，沒有查詢字串也會得到空的 search。若把物件設定改成 URL 物件後才出問題，回看這個差異；外觀短了，不表示匹配範圍完全相同。
同一張自有圖片，只改一段網址
隔離示例讓 Next 的 Image 取作者自有的幾何海報，設定只允許指定本機 HTTP 主機、port 與 /assets/ 路徑，search 為空。允許地址的最佳化回應是可解碼圖片，實際 Image 元件也顯示了海報。
接著只把 HTTP 改成 HTTPS、把 127.0.0.1 改成 localhost、把 /assets/ 改成 /private/，或加上 ?v=1，四個最佳化請求都回 400，訊息是 url 不被允許。這是匹配規則的拒絕，不是說這些地址都已經連線並查到缺檔。
把未允許的 localhost 地址直接交給 Image 元件時，示例也出現未配置主機錯誤。兩種觀察發生在不同入口：元件報錯與最佳化 API 回應不能混成同一個來源主機狀態碼。
本機圖片另涉及本機 IP 的存取限制；這個封閉示例為自己的來源安排了測試設定。正式網站不應因此開啟任意內網取圖，應保留既有安全邊界，使用自己可管理、可公開提供的素材入口。
放行後仍缺圖，要看下一段回應
規則符合只是允許 Next 嘗試取圖。來源仍可能回 404、403、HTML 驗證頁，或不可解碼內容。先核原圖公開路徑、回應及使用權限，不要一看到缺圖，就繼續擴大 remotePatterns。
預設最佳化 loader 取來源圖時不會轉送瀏覽器的所有驗證標頭。你在已登入分頁能開的圖，不一定是 Next 伺服器也能取得的公開圖。這時要按來源的授權方式設計，不把憑證塞進公開設定，也不要求訪客繞過來源保護。
unoptimized 可以改變是否經過預設圖片最佳化，但不會修好來源的權限、HTTPS 或錯誤內容。若要採用，先確認圖片提供方式與效能需求；不要為了隱藏設定錯誤而把整站最佳化關掉。
也要確認拒絕訊息來自哪裡。Next 最佳化入口回的 400 與原圖主機回的 400，並不是同一個判斷。保留完整請求路徑及回應內容；只把狀態碼轉交維護者，可能讓他跑去改來源主機，卻漏掉仍未匹配的 src。
改設定後，同時測允許與拒絕
先保留原設定，再只追加需要的規則。按專案的開發／建置流程重新啟動或產出，確認執行中的版本真的載入了新設定；只修改檔案而仍看舊程序，容易誤判規則沒有效果。
拿一張應允許的圖，再拿一個同主機但不在允許路徑的地址，確認兩邊結果。也測實際來源會帶的 search 與子域名，不要只測一張剛好沒有參數的圖。把地址與拒絕訊息交給維護者，敏感參數先遮蔽。
載入正常後再核 Image 的尺寸與列表裁切；有響應式候選圖時，可接著用currentSrc 的查看方法確認實際選檔。允許來源、圖片成功解碼與選對尺寸，是不同的檢查結果。
參考資料
示例測試版本：Next.js 16.3.8。
評論0