把Next.js的Image改成fill後,網址明明能開,頁面卻像少了一張圖片。先別急著改圖片來源或加寬遠端白名單:如果父容器只有寬度、沒有高度,圖片可能已經載入,只是顯示區域的高度為零。這種情況要從版面尺寸查起。 fill讓圖片填滿父元素提供的區域。父容器需要合適的定位,以及由高度、比例或其他版面條件形成的可用尺寸。圖片本身的原始寬高不會自動把這個容器撐高。理解這個關係後,才能分清載入失敗、零高度與裁切方式三種不同問題。 先看父容器有沒有高度 以下範例的父容器只有寬度。雖然已經設定position: relative,仍沒有建立垂直空間。 import Image from 'next/image'; export default function Demo() { return ( <div style={{ position: 'relative', width: 320 }}> <Image src="/demo.svg" alt="Synthetic demo" fill unoptimized /> </div> ); } 這裡的demo.svg是本地自行製作的測試圖,沒有外站來源、使用者上傳內容或任何腳本。unoptimized明確讓它以原檔呈現,以便把測試集中在版面,而不是圖片最佳化服務。這個選擇不是要示範正式網站應全面關閉最佳化,也不需要開啟允許危險SVG的選項。 在這個容器內,fill產生的圖片使用絕對定位,不會像一般文流中的圖片那樣靠自身高度把父元素推開。若父元素沒有其他內容,也沒有高度限制,量到的高度就可能是零。只改width或再寫一次position: relative,都沒有回答「垂直空間從哪裡來」這個問題。 給圖片一個明確的顯示區域 先用固定尺寸做最容易判讀的對照:保留相同圖片與來源,只為父容器加上高度,並選擇保持比例的填入方式。 <div style={{ position: 'relative', width: 320, height: 180 }}> <Image src="/demo.svg" alt="Synthetic demo" fill unoptimized style={{ objectFit: 'contain' }} /> </div> 這個範例的容器是320乘180。實際網站可以依設計使用響應式寬度和比例,而不是把所有圖片都固定成這個尺寸;關鍵是容器在顯示時要有可計算的寬高。若高度來自父層版面或網格配置,仍應在瀏覽器確認最終尺寸,不要只看樣式檔裡曾經寫過某個值。 relative是此處方便的定位方式,它保留父元素在一般版面中的位置,讓內部絕對定位的圖片有對應區域。官方文件也列出適用的父元素定位條件。不要看到圖片跑到別處,就直接替整個頁面最外層加定位;先找這張圖片真正要填滿的容器,否則它可能依較遠的祖先元素定位。 載入成功也可能完全看不到 本地範例使用Next.js 16.3.8,透過真實Chromium讀取兩個容器及圖片的尺寸。未指定高度的容器是320乘0,裡面的圖片同樣是320乘0;加上高度後,容器和圖片都成為320乘180。兩份使用的圖檔與來源完全相同。 更值得看的是載入資料:兩張圖片的currentSrc都指向本地demo.svg,complete都是true,naturalWidth也都是320。這組結果表示第一張圖並非沒有取到來源,而是載入後沒有垂直顯示空間。Next.js開發環境另提示fill圖片的高度為零,提醒檢查父容器高度。 不能只用complete判定圖片成功,因為它本身也有其他完成狀態;應一起看實際來源、原始尺寸與資源請求。這個案例的原始寬度與來源相互吻合,再配合零高度盒子,才足以把問題指向版面。若你的站點連原始尺寸都是零,則需要回頭查來源與載入結果,不宜直接套用同一結論。 objectFit控制的是區域內怎麼放圖 容器有尺寸後,才輪到選擇圖片在其中的放法。contain會盡量完整保留圖片比例,比例不同時可能留下空白。cover同樣保持比例,但會填滿區域,因而可能裁掉邊緣。是否能接受裁切,要看圖片內容與設計:產品上的文字或人物頭部,不應因為填滿卡片就被截掉。 本例明確使用contain,實測計算樣式也顯示這個值。沒有設定的對照圖片則顯示預設fill。不要把元件的fill屬性與CSS的object-fit: fill當成同一件事:前者決定圖片填入父元素的定位與尺寸方式,後者描述圖像如何放進既有的圖片盒子。 如果換成cover後只剩圖片中央,先核對容器比例,再考慮合適的object-position。這些設定可以調整保留的位置,卻不能救回原圖根本沒有的內容。對文章封面、商品圖和介面截圖也要分別選擇,不應把同一套裁切規則套到所有圖片。 sizes要對應真的版面寬度 正式頁面若使用響應式fill圖片,官方文件建議提供符合顯示寬度的sizes。它描述不同視窗條件下圖片預期占用的寬度,讓瀏覽器從可用來源選擇適合的資源。這與父容器高度是不同問題;補上sizes不會自動替零高度容器建立空間。 例如桌機卡片占內容區的一部分、手機接近整欄時,應依實際斷點與欄位寬度寫條件,不能只複製別人的百分比。檢查時同時讀容器尺寸和currentSrc,確認版面條件與瀏覽器選到的來源。這份本地SVG案例只有一個直接來源,沒有測試多張最佳化尺寸的選擇或下載量改善。 若父容器的寬度也為零,先查是否被隱藏、所在欄位沒有可用空間,或尺寸依賴尚未成立的祖先元素。當頁面包含摺疊區塊、彈窗或切換分頁時,應在真正顯示圖片的狀態再量一次。某個隱藏區塊中的零尺寸,不等於同一張圖片在展開後仍然失效。 alt與來源安全另行處理 版面修正後仍要填寫適合內容的alt。本例只是幾何測試圖,因此使用明確標示測試性質的文字;正式商品照片、說明截圖與裝飾圖片的替代文字,應依它們在頁面上的用途決定。不要拿檔名或一串搜尋關鍵字代替讀者需要的內容說明。 本地圖檔也不等於所有SVG都安全。這個測試圖由自己建立,只用來隔離版面行為;處理來源不明或使用者可上傳的SVG時,要依專案的內容安全設定與檔案處理流程評估。圖片盒子沒有高度時,擴大遠端來源權限或改動安全設定,都不是這個問題的修正方式。 排查順序可以很具體:先核對真正的圖片請求與來源,再量父容器和圖片的寬高,確認定位參照,最後檢查比例、裁切與響應式來源。每一步都對應一個可觀察的結果。這樣即使畫面仍然空白,也能把原因縮小到需要調整的地方,避免反覆換圖卻沒有改到版面條件。 參考資料...
2026-10-05 48 0
文尼先生 2026-10-05

商品網址打錯,頁面顯示「找不到商品」,瀏覽器也沒有報錯,看起來似乎已處理完。可是用開發者工具查看文件請求,狀態仍是200。原因可能很單純:程式只回傳了一段找不到的文字,對Next.js來說,這仍是一張成功產生的頁面。畫面內容與HTTP狀態是兩件事,需要在資料查詢的分支一起決定。 在App Router中,可以呼叫notFound()終止目前路由區段的渲染,交由對應的not-found.js呈現找不到的畫面。不過,不要把它記成「任何情況都會回404」:官方文件區分非串流與串流回應;前者可回404,已開始串流的回應可能仍是200。先分清這個條件,才不會因為一個狀態碼就誤判程式有沒有執行。 先在查詢結果的分支判斷 假設網址是/items/[slug]。以下示範只接受exists這個測試項目,其他值都視為不存在,沒有連接資料庫,也沒有登入權限判斷。 import { notFound } from 'next/navigation'; export default async function ItemPage({ params }) { const { slug } = await params; if (slug !== 'exists') { notFound(); } return <main>Demo exists</main>; } 這裡先等待路由參數,再判斷項目是否存在。實際專案通常會把條件換成資料查詢:取得商品後,如果結果是空值,便呼叫notFound();有資料才繼續回傳頁面。不要在查詢之前憑網址長相猜測是否存在,也不要先使用商品欄位,等程式因空值出錯才改成找不到。 notFound()會拋出框架辨識的特殊錯誤並停止該區段,因此不需要寫成return notFound()才能生效。也要小心範圍過大的try...catch:若把框架的控制流程一起捕捉,再回傳普通文字,原本要交給找不到畫面的分支就可能被自己截住。資料服務的失敗和資料不存在最好各自處理。 用not-found.js準備讀者下一步 在同一個路由區段放置以下檔案,即可提供這個案例的找不到畫面。 export default function MissingItem() { return <main>Demo missing item</main>; } 檔案名稱是not-found.js,不是一般元件取了相似名字便會自動生效。所在路由區段也有意義:商品區段可以提供商品列表連結,其他區段可有各自的說明。要確認專案的資料夾結構,避免只看根目錄檔案就假設所有子路由都使用同一份內容。 對訪客而言,找不到頁應說清楚目前連結沒有對應項目,並提供可用的返回方式。不要把資料庫錯誤堆疊、查詢語句或內部紀錄直接放進頁面。若資料來源暫時故障,也不適合一律寫成商品不存在,否則訪客與維護者都會收到錯誤訊息。錯誤狀態應依實際原因選擇,不能只為了消除畫面例外而把所有失敗收成404。 這個非串流案例實際回了什麼 本地範例使用Next.js 16.3.8,在沒有loading或Suspense邊界的路由中,直接完成上述項目判斷,再發出回應。以HTTP請求分別讀取兩個網址,/items/exists回200;/items/missing回404。不存在的回應包含找不到的內容,也出現noindex指示;存在的回應沒有這個指示。 這個結果證明的是這份範例在回應尚未送出前判斷不存在的行為。它不表示換成遠端資料庫、其他版號、加入載入畫面或經過不同代理後,所有細節都完全一樣。移植時至少要用自己站點的存在與不存在網址各測一次,尤其是實際資料查詢比這個即時分支慢很多的頁面。 查看原始HTML還有一個容易誤會的地方:App Router回應可能攜帶元件資料和備用畫面的定義。這個案例的存在網址中,也能搜尋到找不到畫面的文字,但狀態是200,正常項目文字同樣存在。不能只用「原始碼裡有某個字串」就判定訪客正在看到找不到頁;畫面、回應狀態與資料載荷需要分開核對。 加入串流後為何可能仍是200 官方not-found.js文件說明,串流回應與非串流回應的狀態不同。伺服器一旦已送出回應標頭,後來才發現資料不存在,就不能像尚未開始的回應那樣重新選擇狀態碼。因此,串流情況下找不到的畫面可能出現,HTTP仍維持200。這不是靠在找不到元件裡改一行文字就能修正的事。 若你的實作回200,先查是否有載入邊界、先送出的版面內容或較晚才完成的資料查詢,再看notFound()是否真的執行。不要立即刪除所有載入畫面,或到全站中介層把含某個字串的回應都改404。這些做法可能破壞正常頁面,也會把呈現文字當成路由存在性的依據。 本篇沒有以延遲資料刻意重建串流200案例;這個差異依據官方文件列出。本站若需要特定路由的非串流404,應把資料判斷時間和回應流程當作該路由的設計條件,另外實測。訪客看到清楚的找不到內容仍然必要,但它不能代替傳輸層的檢查。 查驗時先看文件請求 開發者工具的Network中,先找到這次直接載入網址的文件請求,查看狀態與回應,再核對頁面呈現。頁面內切換路由時可能發出框架資料請求;圖片、字型或其他資源的200也不代表商品頁是200。測試前應確認自己正在讀哪一個請求,避免混用快取畫面或上一次導覽結果。 可以用一個確定存在的slug和一個確定不存在的slug比較,同時記下測試環境是否啟用串流。若站點有CDN或反向代理,再核對公開網址的回應,不能只憑本地開發伺服器推定正式結果。伺服器紀錄也應能對回這次路由和時間,幫助判斷狀態是在應用程式還是其他環節產生。 notFound()的文件另說明它會加入搜尋引擎用的noindex標記。本例只核對回應中出現這個標記,沒有測試搜尋引擎爬取、收錄或移除結果。若修正已存在的錯誤網址,仍要檢查實際公開回應與後續索引狀態;一份本地HTML不能代表Google已經完成處理。 別把權限失敗混成資料不存在 商品不存在和使用者無權查看,是兩個不同的問題。有些專案會依自己的安全與產品政策,用找不到回應隱藏資源是否存在;這需要明確的權限流程,並不是呼叫notFound()便自動完成。這份示範只判斷測試項目,沒有展示或驗證任何存取控制。 實作時保留清楚的分支:路由參數有效後查資料,資料存在後再依需求處理可見範圍,最後產生頁面。若查詢本身故障,讓故障進入適合的錯誤處理。這樣維護者才看得出某次回應是正常的不存在,還是服務出了問題;訪客也能得到與實際情況相符的下一步。 參考資料 Next notFound Next not-found UI Next動態路由 Next錯誤處理 MDN404
2026-10-05 64 0
文尼先生 2026-10-05

升級Next.js後,原本的 cookies().get('theme')提示不是可直接使用的cookie store。先看你呼叫的是next/headers提供的cookies函式。現行API是非同步的,應先await取得store,再讀其中的值。 這個修正處理的是伺服器讀取當次請求cookie的介面,不是把cookie搬到全域變數,也不是在瀏覽器改用localStorage。讀者先用兩份合成Cookie標頭測同一條Route Handler,就能確認它讀的是各自請求帶來的值。 先取得store,再呼叫get 下面是最小的App Router Route Handler。它只讀demo_theme並回JSON,不登入、不寫cookie,也不連資料庫。 import { cookies } from 'next/headers' export async function GET() { const store = await cookies() const theme = store.get('demo_theme')?.value ?? 'none' return Response.json({ theme }) } 將它放在 app/cookie/route.js,GET處理函式要是async,才能在裡面await。先解析cookies這個非同步操作,再對store呼叫get。不要寫成 await cookies().get(...),因為那會在等待之前先嘗試對Promise呼叫get。 也不要忘記取得的是cookie物件,需要讀value。.get()找不到該名稱時可能沒有物件,所以範例採可選鏈與預設字串。這個預設只讓示範結果容易辨認,不是你所有業務功能都應採相同的缺值策略。 舊版同步例子不代表目前介面 官方升級指南說明,Next.js15引入非同步的請求API,包含cookies。舊版文件或片段可能仍用同步寫法;維護站點時先確認package與鎖定版本,再按對應指南改。 本文真案例是Next.js16.3.8、React19.3.0,使用await cookies。不把舊站曾經可同步讀取當作現版可依賴的行為,也不要求每個舊專案只因看到本文就立刻升級。這份教學解決的是目前已使用非同步介面的程式怎麼正確取值。 如果編輯器還是顯示與文件不符的型別,也要核實際安裝版本與匯入來源。另一個套件裡同名的cookies方法,不一定是這個API。先把它來自哪裡讀清楚,避免只在呼叫前後加await卻改錯東西。 同一路徑,兩個請求各帶自己的值 本機測試可以分別送light與dark。這些是合成偏好值,不含帳戶、工作階段或權杖。curl的Cookie標頭讓你直接看到輸入,不需要先操作真會員登入。 curl -H 'Cookie: demo_theme=light' http://127.0.0.1:3000/cookie curl -H 'Cookie: demo_theme=dark' http://127.0.0.1:3000/cookie 本文實際HTTP結果是兩次都回200;第一份JSON的theme是light,第二份是dark。這說明同一個處理函式讀到了當次不同的Cookie標頭,不是把第一次讀到的store留著讓所有請求共用。 這份測試沒有觀察瀏覽器自動送cookie的範圍,也沒有修改正式cookie配置。接回網站後,要再核瀏覽器真正發出的請求是否帶預期名稱與值。手動指定標頭能驗證解析介面,不能取代真瀏覽器的domain、path與發送條件。 cookie是請求資料,不是全域設定 不要在模組最外層提前讀cookies,再把結果當成全站固定偏好。cookie跟當次請求有關,應在合適的伺服器請求上下文裡讀。把某一次的值快取成大家共用,會讓不同使用者的結果混在一起。 如果頁面需要依偏好選擇畫面,可以在Server Component裡await cookies,取得並整理允許值,再傳必要資料給顯示元件。選dark或light等固定集合時,對未知值保留明確的預設,不要把任意cookie字串直接當成設定名稱或資料查詢。 讀到cookie也不表示它可信或能單獨決定授權。本例只是顯示合成theme;真登入與資源權限仍沿既有服務驗證。把這兩種需求分開,能讓取值示例保持簡單,不會把任意客戶端提供的字串當成已核身分。 NextRequest.cookies是另一個入口 Route Handler若使用NextRequest,該請求物件也有自己的cookies介面。它與next/headers的cookies函式不是同一個呼叫方式,不能因為名字相似就交換使用,或對兩者都機械加相同await。 export function GET(request) { const theme = request.cookies.get('demo_theme')?.value ?? 'none'...
2026-10-05 47 0
文尼先生 2026-10-05

在App Router的page加了一顆有onClick的按鈕,建置卻報事件處理函式不能傳到Client Component。先確認這份page是否仍是預設的Server Component。要在瀏覽器處理點擊與本地互動狀態,應把那一小段放進Client Component,而不是在伺服器頁直接加入一般的事件函式。 修正不一定需要把整頁都加上use client。頁面的資料讀取、文字與其他伺服器工作可以保留原處,只把計數按鈕或其他互動區域抽成客戶端元件。這樣依賴與責任比較清楚,也避免只為一顆按鈕搬動整個資料流程。 這份page預設在伺服器側處理 下面是最小問題寫法。它沒有use client,卻在原生button上帶一般onClick函式。 export default function Page() { return <main> <button onClick={() => console.log('click')}>計數</button> </main> } 函式裡的console.log本身不是重點,換成setState或其他任意click函式也沒有解決元件邊界。問題是伺服器渲染的這段UI,要把一個一般事件處理函式留給瀏覽器,卻沒有合適的Client入口。 本文在Next.js16.3.8與React19.3.0測試此page,next build --webpack在prerender階段失敗,結束碼1,訊息指出事件處理函式不能傳給Client Component props,並建議把需要互動的部分轉成Client元件。這不是單純編輯器警告,而是真建置輸出。 先建立最小Counter客戶端元件 在單獨檔案最前面加 'use client',再使用React的本地狀態與事件。指令要位於匯入之前,讓框架辨認這份檔案是Client邊界入口。 'use client' import { useState } from 'react' export default function Counter() { const [count, setCount] = useState(0) return <button onClick={() => setCount(count + 1)}> Count {count} </button> } Counter自行定義點擊函式,不要求伺服器把一段一般函式傳進來。這個最小例子只改本地計數,沒有呼叫API或保存資料。先讓它正常互動,再接回真正的功能,比一開始把整套訂單操作包進去更容易核對問題。 現在Server page只需匯入並放置Counter。這一份page仍可以保持Server Component。 import Counter from './counter' export default function Page() { return <main> <h1>Server page</h1> <Counter...
2026-10-05 48 0
文尼先生 2026-10-05

在 app/items裡新增 route.js,打算讓同一條路徑既顯示商品頁,也回傳JSON。建置卻提示 /items/page與 /items/route指向相同路徑。這不是把函式名稱改一下就能修好的錯誤;兩個檔案正在爭用同一個URL。 App Router的 page提供頁面UI,route提供Route Handler。兩者不能放在同一個路由區段,讓同一條路徑各自處理請求。若網站需要商品頁與商品資料API,給它們各自的路徑,再讓呼叫端明確使用對應入口。 資料夾相同,就先看URL是否相同 問題結構通常長這樣。layout是共用外殼,不是這次衝突的主角;衝突來自items底下兩個具有回應責任的檔案。 app/ layout.js items/ page.js route.js page.js可以匯出頁面元件;route.js則匯出GET、POST等處理函式。即使函式寫得完全不同,這兩個檔案還是落在同一個路由區段。不要把「不同檔名」當成「不同網址」,也不要期待框架讀內容後自行猜使用者想要頁面還是JSON。 同樣地,把page改成TypeScript、route改成JavaScript不會分開路徑。副檔名決定程式語言處理,不是幫URL新增區段。衝突位置若在更深層資料夾,沿資料夾名稱算出實際路徑,會比反覆改副檔名更有用。 把API移到明確的資料路徑 一種常見結構是讓 /items保留頁面,將JSON放到 /api/items。這裡的api只是你選的路徑名稱;Route Handler並不是只能放在api資料夾,選這個名字是讓團隊容易辨認入口用途。 app/ layout.js items/ page.js api/ items/ route.js 頁面範例只顯示文字,API回合成ID,兩者不接業務資料。把這個最小結構跑通,才能再接回真正的商品清單。 // app/items/page.js export default function ItemsPage() { return <main>Items demo page</main> } // app/api/items/route.js export function GET() { return Response.json({ items: [11, 13] }) } 修改路徑後,呼叫端也要改成 /api/items,不要後端移好了,前端仍向 /items發fetch。那樣可能收到HTML頁面,再在 response.json()報解析錯誤,讓你誤以為API只是回應格式壞掉。 真建置錯誤,與修正後兩種HTTP回應 本文案例使用Next.js16.3.8與React19.3.0。先在items同時放page與route,執行 next build --webpack,建置結束碼為1,錯誤明確指出兩個頁面解析到相同路徑,並列出 /items/page與 /items/route。 之後保留page,把route移到api/items,再啟動測試專案。請求 /items回200,內容類型是HTML,畫面標記為Items demo page;請求 /api/items也回200,但內容類型是JSON,資料為 {"items":[11,13]}。這份修正比較使用實際HTTP回應,不只是檔案結構看起來不同。 curl -i http://127.0.0.1:3000/items curl -i http://127.0.0.1:3000/api/items 測試時別只看兩個狀態碼都200。確認Content-Type與內容,才能知道拿到頁面還是資料。本例在修正後以開發伺服器核兩個入口,不把它稱為完整部署驗收;自己的專案最後仍應執行適合的建置檢查,確認其他路由沒有一起出問題。...
2026-10-04 59 0
文尼先生 2026-10-04

把舊版動態頁搬到新版Next.js後,原本的 params.slug不能照常使用,型別也提示params像一個Promise。先確認專案版本與這個頁面使用App Router。現行動態路由的params是非同步值,Server Component要先等待它,再從解析出的物件取slug。 這不需要把整頁改成Client Component,也不代表網址裡的slug需要先呼叫某個API。問題在框架提供參數的介面變了。本文用兩條不同網址驗證同一個動態頁,再分清路徑參數、查詢參數與靜態生成,避免看到Promise就改錯資料來源。 動態資料夾的名字決定key 在App Router中,app/items/[slug]/page.js的中括號資料夾代表一個動態區段。請求 /items/alpha 時,slug的值是alpha;請求 /items/bravo 時則是bravo。若資料夾叫 [id],解析物件的key就叫id,不會因為你的變數寫slug就自動更名。 export default async function ItemPage({ params }) { const { slug } = await params return <main><h1>{slug}</h1></main> } Server頁可以是async函式。在函式裡解開params,再把普通字串用於查詢或渲染。這份最小頁只顯示字串,不查資料庫,也不把字串當成可以任意存取的檔案路徑;先核到這層,再接回真正的內容查詢。 容易寫錯的是 await params.slug。它在await之前就先嘗試讀params上的slug;你需要等的是params這個Promise本身。拆成兩行 const resolved = await params與 resolved.slug也可以,只要先後順序清楚。 TypeScript也要標出Promise 如果原頁面的型別仍寫成普通物件,會把舊假設留在編輯器提示裡。新版頁面型別可以把非同步參數直接表達出來。 export default async function ItemPage({ params, }: { params: Promise<{ slug: string }> }) { const { slug } = await params return <main><h1>{slug}</h1></main> } 這個型別對應單一 [slug]區段。catch-all區段是陣列等其他形狀,不能把每一種動態路由都標成string。依資料夾規則選型別,再驗證業務上允許的值;型別描述不等於使用者輸入已符合你的產品規則。 官方文件指出,Next.js14與更早版本的params是同步prop,15保留過同步存取以協助相容,但這種方式會被淘汰。本文真案例使用16.3.8,採現行非同步寫法。維護舊站時先看實際依賴與升級指南,不要對所有版本一律套同一個錯誤訊息。 用兩個slug測,避免只看固定字串 最小測試專案只需基本layout與上述動態頁。啟動後分別請求alpha與bravo,確認兩個回應都正常,而且各自顯示正確值。只測alpha一個網址,可能漏掉程式把測試值硬寫在畫面的錯誤。 curl http://127.0.0.1:3000/items/alpha curl http://127.0.0.1:3000/items/bravo 本文在Next.js16.3.8、React19.3.0的隔離App Router案例中,兩個請求都回200,h1分別是alpha與bravo。這證明params解析與頁面路由對上;它沒有證明任何商品或會員資料已存在,因為範例沒有接業務資料。...
2026-10-04 47 0
文尼先生 2026-10-04

儲存完資料後呼叫 redirect('/done'),頁面卻沒有移動,反而在日誌看到 NEXT_REDIRECT。若程式把整段儲存與導向包在同一個 try/catch,先檢查 catch是否把導向攔住了。Next.js的 redirect() 會透過拋出例外結束目前處理;這個例外需要交回框架,才能完成導向。 這種情況不必先改網址或重做成功頁。把「處理儲存錯誤」和「成功後導向」分開,通常就能看出差別。本文用 App Router的 Route Handler 做最小案例,再說明 Server Action和客戶端按鈕該怎麼選,避免把不同情境的回應狀態混在一起。 這個catch也會接住redirect 下面的 try包含兩件事:執行一個示範工作,與呼叫導向。示範工作只返回字串,沒有接資料庫;我們要觀察的是控制流程,而不是儲存功能。 import { redirect } from 'next/navigation' export async function GET() { try { await Promise.resolve('saved') redirect('/done') } catch (error) { return Response.json({ error: error.message }) } } 這段可放在測試專案的 app/bad/route.js。看起來像任何錯誤都能轉成 JSON,問題也正出在「任何」:導向本身拋出的例外同樣落入這個 catch。回傳 JSON後,框架收到的是你的正常回應,導向控制流程已經被改掉。 此時使用者可能看到錯誤文字,網路面板卻顯示 200。原因是 Response.json沒有指定其他狀態碼時,產生的就是預設正常回應;它不會因為內容有 error欄位,就自動成為 HTTP錯誤。這只是這個範例的結果,不是 Next.js規定所有被捕捉的例外都回200。 不要用 error.message === 'NEXT_REDIRECT' 當作整個應用程式的固定分類規則,也不要手動回傳某個內部 digest格式冒充框架導向。內部控制訊號不是給你拼接的回應 API。最容易理解的修正是縮小 try的範圍,讓成功路徑直接呼叫框架公開的導向方法。 讓redirect在try外執行 把需要捕捉的工作留在 try內,失敗時回傳失敗結果;只有工作完成,才會走到外面的 redirect。不要在 catch後不分成功與失敗就一律導向。 import { redirect } from 'next/navigation' export async function GET() {...
2026-10-04 52 0
文尼先生 2026-10-04

Next.js網站換了API網址,容器裡也能讀到新環境變數,瀏覽器卻繼續送往舊網址。先確認程式讀的是不是 NEXT_PUBLIC_ 開頭的值。這類變數在直接引用時,會於建置期間放進送給瀏覽器的JavaScript;只修改啟動環境,通常不會改掉已產生的客戶端程式。 本文聚焦一個部署問題:同一份建置產物移到另一個環境,為何公開設定還停在建置時的值。用BUILD_A建置、RUNTIME_B啟動的小頁面看結果,再分清何時要重新建置,何時應由伺服器提供可變設定。它不是清快取的通用指南,也不處理所有伺服器環境變數讀取方式。 先把變數讀取位置找出來 在Client Component或會進入瀏覽器bundle的程式裡,找到具體的 process.env.NEXT_PUBLIC_API_BASE。注意是直接寫明變數名稱。不要只看.env檔有沒有值;檔案存在、建置程序讀得到、客戶端程式採用的是哪個值,是三件需要對應的事。 'use client' export default function ApiLabel() { const base = process.env.NEXT_PUBLIC_API_BASE return <p>{base}</p> } 這段在建置時若讀到測試API網址,部署該bundle後,直接引用通常就已固定成那個字串。伺服器重啟時設另一個同名值,不會重新加工舊JavaScript。既然檔案內容沒改,換容器的啟動參數也不等於重新產生客戶端設定。 查程式時也看有沒有同名常數、fallback或其他設定來源。如果讀取失敗後自動退回測試網址,畫面就可能一直看似正常,實際請求卻去了錯環境。先把讀取位置與建置參數對上,再判斷是否另有快取或部署版本問題。 一個公開標籤就能看出固定時點 示例使用一個Client Component顯示公開標籤,不需要真API、金鑰或會員資料。建置前把 NEXT_PUBLIC_CASE_LABEL 設為BUILD_A,完成建置後,再把啟動環境的同一變數改為RUNTIME_B。 'use client' export default function PublicValue() { return ( <p> {process.env.NEXT_PUBLIC_CASE_LABEL} </p> ) } 在PowerShell裡可分兩階段操作。使用你的專案正常build與start腳本;下面例子顯示的是時點,不要求你更改整個部署方式。 $env:NEXT_PUBLIC_CASE_LABEL = 'BUILD_A' npm run build $env:NEXT_PUBLIC_CASE_LABEL = 'RUNTIME_B' npm run start 本文示例建置成功後,啟動服務回傳的頁面仍包含BUILD_A,客戶端chunk也包含BUILD_A;啟動時改成的RUNTIME_B沒有出現在該頁回應。這是公開值已固定於建置產物的證據,不能因此推論所有環境變數在所有路由裡都固定。 需要新公開值時,重新建置再部署 若網站的設計本來就是每個環境各產生一份bundle,修法通常是把正確公開值放到建置階段,重新build,部署這份新產物。CI裡只在「啟動容器」步驟設定值,但「建置映像」步驟沒給它,仍可能得到錯的客戶端設定。 保存每次建置使用的公開參數與產物識別,再核對正式站實際提供的chunk。不要在記錄中保存私密變數值。建置成功後確認部署服務採用了新映像或新目錄,並且HTML引用的是本次產物;只看到CI綠燈,還不能證明訪客拿到新bundle。 如果使用Docker多階段建置,公開變數需在執行build的階段可用。放到最後執行階段的ENV只影響那個階段的程序環境,不會回頭改先前編譯出的檔案。用同一映像從測試環境推到正式環境時,尤其要先決定公開設定是否應跟映像一起固定。 想讓同一份產物跨環境,先換設定路徑 若同一份bundle必須在啟動後讀到不同API位置,就不要把可變值只放在NEXT_PUBLIC直接引用裡。可以由伺服器在執行時讀環境,透過受控端點回傳允許公開的設定;客戶端啟動後取得這份設定,再初始化需要它的程式。這是另一種架構,要處理取得失敗、載入順序與快取,不是改一個前綴就能完成。 回傳的設定只能包含可公開資料,不能把整個 process.env 序列化送出去。伺服器私密API金鑰應留在伺服器,由受控的後端請求使用。若某第三方服務提供的是可公開識別碼,仍需按該服務的權限及來源限制設計,不能只因為它叫「key」或加了NEXT_PUBLIC就自行判定安全。 伺服器讀取還要核對路由的渲染與快取行為。App Router動態渲染時可以讀取執行期環境變數;靜態預產生的內容則可能在建置時取得值。本文示例是公開直接引用,與伺服器動態讀值不同。修改為Runtime設定端點後,應另測它在目前Next.js版本下是否確實每次按預期讀值。 動態屬性名稱不是繞過建置的可靠方法 const key = 'NEXT_PUBLIC_API_BASE' const value = process.env[key] const env =...
2026-10-04 55 0
文尼先生 2026-10-04

訪客按送出,按鈕變成「送出中」,等了很久卻無法再按。先看請求是不是還在等待,還是已經回錯誤而畫面沒解除狀態。兩種原因的修法不同;把按鈕重新打開,只解決了表面操作,還要讓訪客知道這次送出到底到了哪一步。 以下用 Next.js 16、React 19 的 App Router 表單作例子。Client Component 以 useActionState 處理表單 action,再向自己的 Next Route Handler 發 POST;這不是 Server Action,也沒有連接正式資料庫、寄信或付款。 把等待、錯誤與完成分開顯示 等待時顯示「送出中,請稍候」,暫時停用這個送出按鈕。取得可用錯誤回應後,等待應結束,保留輸入,說明原因並提供重試;成功時則按接收端真正回傳的結果顯示,不要只因請求有回應就寫「已寄送」。 按鈕原本就因缺資料而停用,屬於送出前的條件。可先看停用按鈕旁怎麼說明原因。這篇處理的是已送出後的等待生命週期,不把欄位格式合格當成伺服器已接收。 讓第一次失敗,再用同一段文字重試 示例 Route Handler 先檢查訊息,再等待約 1.8 秒;第一個有效嘗試回 503,第二個回 200。故障次序是為了重現操作安排的,嘗試次數只控制示例,不是正式提交身分或防重複機制。 真實 Next.js 示例正在等待自己的 POST 回應;文字仍在輸入框。 第一次取得 503 後,畫面解除等待,按鈕改為「重試」,訊息仍是剛才的文字。按重試會再發一個 POST;第二次取得 200 後,示例顯示「請求已成功回應;未保存或寄送資料」。它只確認這個示例端點完成回應。 服務回錯誤後,等待結束,保留輸入並提供重試。 讓 pending 跟著真實非同步工作 在 Client Component 檔案開頭加入 'use client',從 React 匯入 useActionState 與 useState。useActionState 的 action 接收上一份 state 與這次 FormData,回傳下一份結果;不要把第一個參數誤當表單資料。 這個 action 讀取示例端點約定的 JSON message,並用 HTTP 狀態決定成功或錯誤。片段中的 /api/submit 必須有自己實際建立的 Route Handler,接收 POST JSON 並回相應狀態及 message;貼上前端函式不會自動建立接收端。...
2026-10-04 61 0
文尼先生 2026-10-04

外部圖片直接打開有圖,放進 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...
2026-10-04 63 0
文尼先生 2026-10-04

Next.js 列表切換後,網址已經是 ?q=shop,搜尋標題卻還寫 blog;按一下瀏覽器重新整理,標題又正常了。這種差異不一定是快取,也不一定是 Link 壞掉。先找出畫面讀的是目前網址,還是元件第一次建立時留下的值。 這裡用 App Router 的搜尋條件作例子。站內 Link 的基本選擇可先讀Next.js 站內連結用 Link 還是 a;本文接著處理「連結已正確切換,但畫面狀態沒跟上」的問題。 先決定哪個值應該跟著網址走 搜尋結果、分類與頁碼通常需要能直接開啟、分享,也要在重新整理後保持同一條件。若你的列表把 q 定義為搜尋條件,就讓結果與顯示的已套用條件讀同一個網址參數。別讓網址是一份資料,元件又保留另一份互不更新的副本。 輸入框裡尚未送出的文字則不同。訪客正在把「部落格」改成「部落格模板」,不代表結果已經套用新條件。可以用本地 state 保存草稿,按送出後才更新網址。這樣畫面能分清「正在編輯」與「已套用」,也不會因每打一個字就換頁而打斷操作。 先在紙上列出三項:網址裡的 q、結果實際使用的 q、輸入框草稿。若前兩項不一致,就查讀取流程;若只有草稿不同,先確認它是否本來就應保留。不要為了讓所有數字一致,直接清掉訪客還沒送出的內容。 最容易漏看的,是 useState 的初始值 下面兩行看起來都在讀 q,生命週期卻不同: const q = useSearchParams().get('q') ?? ''; const [initialQ] = useState(q); q 來自這次渲染取得的網址參數;initialQ 是 state 第一次初始化時的值。React 不會因下一次傳給 useState 的初始參數改了,就自動覆寫既有 state。若元件仍保留著,切換到 shop 時,q 可以是 shop,initialQ 卻仍是 blog。 這不表示元件完全沒有重新渲染。它可能已經讀到新 q,只是畫面仍選擇顯示 initialQ。排查時把兩個值暫時並排顯示,通常比單看「畫面沒動」更容易定位。若目前 q 已更新,就先查用了哪個變數,不必急著清除整站快取。 同一個共用 layout,三種操作的差異 以下以 Next.js 16 的 App Router 搜尋示例說明。首頁與模板列表共用 layout,裡面的 Client Component 同時顯示目前 q、初始化快照及草稿。由 /?q=blog 填入「部落格模板」,再點原分頁的 Link 前往 /products?q=shop。...
2026-10-04 64 0
文尼先生 2026-10-04
顯示驗證碼
沒有帳號?註冊  忘記密碼?