試與故障排查完全指南：從節(jié)點數(shù)據(jù)缺失到媒體下載與預(yù)覽失效)
gatsby-source-wordpress 調(diào)試與故障排查完全指南從節(jié)點數(shù)據(jù)缺失到媒體下載與預(yù)覽失效【免費下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址: https://gitcode.com/gh_mirrors/ga/gatsby導(dǎo)讀gatsby-source-wordpress是 Gatsby 生態(tài)中連接 WordPress經(jīng)由 WPGraphQL的核心數(shù)據(jù)源插件。本文以官方 debugging-and-troubleshooting.md 為骨架系統(tǒng)梳理節(jié)點數(shù)據(jù)缺失、GraphQL 報錯、WordPress 50x 錯誤、請求超時、媒體文件下載失敗/被跳過、Preview 模板損壞與預(yù)覽不更新等高頻問題的定位思路與修復(fù)手段并結(jié)合插件源碼fetch-graphql.ts、write-queries-to-disk.js、declare-plugin-options-schema.js解釋底層原理。讀完本文你將掌握一套可復(fù)制的「先在 Gatsby 外復(fù)現(xiàn)、再借助插件調(diào)試選項定位、最后針對性調(diào)整配置」的排查方法論。一、Node sourcing節(jié)點數(shù)據(jù)拉取階段的故障排查Node sourcing節(jié)點數(shù)據(jù)拉取是插件從 WPGraphQL 拉取 WordPress 內(nèi)容并轉(zhuǎn)化為 Gatsby 節(jié)點的核心階段絕大多數(shù)「數(shù)據(jù)不對、構(gòu)建報錯、構(gòu)建卡死」問題都發(fā)生在這個階段。下文按癥狀分類給出排查步驟。1.1 Gatsby 中數(shù)據(jù)缺失字段返回 null 或空數(shù)組當(dāng)某些字段在預(yù)期有值的情況下返回null或空數(shù)組時請按以下步驟定位第 1 步在 Gatsby 與 WPGraphQL 兩側(cè)分別執(zhí)行同一語義的查詢。使用第三方 GraphQL 客戶端如 GraphQL Playground直接對 WordPress 的 WPGraphQL 端點發(fā)查詢。注意不要使用 wp-graphiql 調(diào)試因為它帶有認(rèn)證態(tài)而 Gatsby 拉取數(shù)據(jù)時是不帶認(rèn)證的。例如 Gatsby 側(cè)查詢是這樣{ allWpPage { nodes { id title } } }那么在 WPGraphQL 端點直接執(zhí)行的等價查詢是{ pages { nodes { id title } } }第 2 步對比兩側(cè)返回數(shù)據(jù)。若兩邊返回的數(shù)據(jù)一致、但你認(rèn)為應(yīng)該有數(shù)據(jù)很可能問題出在 WPGraphQL 或你使用的 WPGraphQL 擴(kuò)展上。先回到 WordPress 后臺編輯對應(yīng)文章確認(rèn)這些字段確實有數(shù)據(jù)排除「數(shù)據(jù)本身就不存在」的可能。若兩側(cè)數(shù)據(jù)不一致進(jìn)入第 3 步啟用插件調(diào)試選項檢查插件內(nèi)部生成的查詢。第 3 步開啟writeQueriesToDisk調(diào)試選項。{ resolve: gatsby-source-wordpress, options: { debug: { graphql: { writeQueriesToDisk: true, }, }, }, }第 4 步重新運行g(shù)atsby develop或gatsby build。第 5 步查看落盤目錄。在你的 Gatsby 項目根目錄下會出現(xiàn)your-app/WordPress/GraphQL/其中為每個被拉取的節(jié)點類型各建一個子目錄。例如本例缺失標(biāo)題的類型是 Page則查看WordPress/GraphQL/Page/。第 6 步打開node-list-query.graphql并復(fù)制其中查詢。第 7 步把查詢粘貼到 GraphQL Playground并附帶查詢變量{ first: 100, after: null }第 8 步執(zhí)行并對比結(jié)果。結(jié)果同樣缺失數(shù)據(jù)說明這是 WPGraphQL 側(cè)或你使用的 WPGraphQL 擴(kuò)展的 bug。建議到 WPGraphQL 社區(qū)尋求幫助或到相應(yīng)擴(kuò)展倉庫提交 issue。為了幫助對方定位請逐個注釋掉復(fù)制出來的查詢里的字段二分排查出「哪一組字段組合」會觸發(fā)問題。常見根因提示如果你在使用 ACF 且在不同的字段組里給多個字段起了相同名稱極容易引發(fā)此類問題。找出沖突的字段名并重命名即可。結(jié)果數(shù)據(jù)完整說明是gatsby-source-wordpress自身的 bug請到 Gatsby 倉庫提交 issue 并附上復(fù)現(xiàn)信息。源碼佐證插件在啟動時會根據(jù)遠(yuǎn)端 schema 為每個可拉取類型生成 3 個查詢文件——node-list-query.graphql分頁列表、node-single-query.graphql單節(jié)點、node-preview-query.graphql預(yù)覽外加RootQuery/non-node-root-query.graphql非節(jié)點根字段。只有當(dāng)遠(yuǎn)端 schema 發(fā)生變更remoteSchema.schemaWasChanged時才會重新寫入寫入邏輯見 write-queries-to-disk.js。1.2 Node sourcing 階段的 GraphQL 報錯如果構(gòu)建因 GraphQL 請求返回的錯誤而終止終端輸出會明確指出報錯對應(yīng)的類型type。GraphQL 返回錯誤幾乎總是 WP 側(cè)的 bug。復(fù)現(xiàn)步驟如下同樣開啟debug.graphql.writeQueriesToDisk配置同上。重新運行g(shù)atsby develop或gatsby build。當(dāng)進(jìn)程因 GraphQL 錯誤退出時記下報錯對應(yīng)的 GraphQL 類型然后打開your-site/WordPress/GraphQL/[TypeOfErroringQuery]/node-list-query.graphql。該文件內(nèi)即為節(jié)點拉取時真實發(fā)送給 WPGraphQL 的查詢可據(jù)此在 Gatsby 之外復(fù)現(xiàn)錯誤、單獨調(diào)試。如何讓報錯信息更可讀從 fetch-graphql.ts 的報錯處理可以看到插件會盡力給出錯誤路徑形如mediaItems.nodes[55].mediaDetails.meta.focalLength、錯誤類別與行列號并提示若想獲得更詳細(xì)的錯誤消息可在wp-config.php中加入define( GRAPHQL_DEBUG, true );。1.3 WordPress 50x 錯誤500/502/503/504節(jié)點拉取階段遇到 50x 系列錯誤通常是以下兩種原因之一原因一單次查詢過重或并發(fā)過高壓垮了 WP 服務(wù)器。嘗試把schema.perPage從默認(rèn)的100調(diào)低例如 20~50減少單次請求拉取的節(jié)點數(shù)嘗試調(diào)低schema.requestConcurrency限制同一時刻發(fā)往 WPGraphQL 的并發(fā) GraphQL 請求數(shù)默認(rèn)值為15。原因二某條 GraphQL 查詢在 WP 服務(wù)器上觸發(fā)了不可恢復(fù)的 PHP 錯誤。這種情況請按 1.2 節(jié)的步驟復(fù)現(xiàn)并調(diào)試 GraphQL 錯誤。源碼佐證在 fetch-graphql.ts 中插件通過errorIs500ish識別 500/502/503/504并對 50x 錯誤自動重試最多 5 次retries: 5重試仍失敗后會以CODES.WordPress500ishError終止構(gòu)建并輸出「服務(wù)器可能過載」的提示與降低requestConcurrency/previewRequestConcurrency/perPage的配置建議。若錯誤為 500 且非重試可解決還會建議你在wp-config.php中開啟WP_DEBUG、WP_DEBUG_LOG、GRAPHQL_DEBUG后查看 WordPressdebug.log定位 PHP 錯誤。1.4 Node sourcing 超時節(jié)點拉取超時通常意味著你的 WP 服務(wù)器限制的并發(fā)請求數(shù)低于插件同時發(fā)起的請求數(shù)插件會同時為多個類型并發(fā)發(fā)請求。兩條解決路徑提升服務(wù)器能力調(diào)優(yōu)或更換服務(wù)器配置提高可承載的并發(fā)連接數(shù)降低插件并發(fā)把schema.requestConcurrency調(diào)到低于服務(wù)器可承載的并發(fā)數(shù)。如何測定服務(wù)器能承受多少并發(fā)開啟verbose選項{ resolve: gatsby-source-wordpress, options: { verbose: true, }, },重新構(gòu)建。終端會打印一長串插件正在拉取的類型Page、Post、User 等每行右側(cè)標(biāo)注了該類型已拉取的節(jié)點數(shù)。列表底部有一些尚未返回節(jié)點的類型。從「最后一個像被凍結(jié)住的類型」往列表頂部數(shù)數(shù)出來的數(shù)量大致就是服務(wù)器能承受的并發(fā) GraphQL 請求數(shù)。注意舊環(huán)境變量GATSBY_CONCURRENCT_DOWNLOAD已廢棄現(xiàn)在統(tǒng)一使用schema.requestConcurrency配置項。超時與構(gòu)建失敗的更多細(xì)節(jié)插件默認(rèn)請求超時為schema.timeout 30000毫秒超時后會以CODES.Timeout報錯退出并提示你檢查 URL 是否正確、是否需要提升服務(wù)器資源或降低perPage。相關(guān)實現(xiàn)見 fetch-graphql.ts。二、Media File Download媒體文件下載問題2.1 媒體文件下載錯誤服務(wù)器被壓垮媒體文件下載階段最主要的錯誤是并發(fā)請求過多導(dǎo)致遠(yuǎn)端服務(wù)器過載。gatsby-source-wordpress會把媒體文件下載與 GraphQL 數(shù)據(jù)拉取分開限制并發(fā)GraphQL 請求并發(fā)schema.requestConcurrency默認(rèn)15媒體文件下載并發(fā)type.MediaItem.localFile.requestConcurrency默認(rèn)100。遇到下載錯誤時把schema.requestConcurrency調(diào)到低于默認(rèn)值100注意該小節(jié)文檔語境下指媒體下載并發(fā)即localFile.requestConcurrency的場景再逐步實驗找到服務(wù)器能穩(wěn)定承載的「最大并發(fā)數(shù)」。若 WP 服務(wù)器在導(dǎo)入/構(gòu)建時崩潰優(yōu)先降低該值。2.2 媒體文件被跳過下載Skipped媒體文件未下載通常有兩大原因文件大小超過了type.MediaItem.localFile.maxFileSizeBytes配置上限默認(rèn)15728640字節(jié)即 15MB文件的 MIME 類型被列入了type.MediaItem.localFile.excludeByMimeTypes默認(rèn)[]即不排除任何類型。排查因maxFileSizeBytes被跳過的文件啟動gatsby develop執(zhí)行以下 GraphQL 查詢?? 務(wù)必將gt過濾器中的數(shù)字替換為你 gatsby 配置中maxFileSizeBytes的實際值query TOO_LARGE_FILES { allWpMediaItem(filter: { fileSize: { gt: 15728640 } }) { nodes { id sourceUrl fileSize } } }排查因excludeByMimeTypes被跳過的文件啟動gatsby develop執(zhí)行以下查詢?? 務(wù)必將in過濾器中的 MIME 類型數(shù)組替換為你配置中的實際值query MIME_TYPE_EXCLUDED { allWpMediaItem(filter: { mimeType: { in: [image/jpeg, video/mp4] } }) { nodes { id sourceUrl mimeType } } }相關(guān)配置速查詳見 plugin-options.md配置項默認(rèn)值作用type.MediaItem.localFile.excludeByMimeTypes[]按 MIME 類型阻止下載對應(yīng)文件type.MediaItem.localFile.maxFileSizeBytes1572864015MB阻止下載超過指定字節(jié)數(shù)的文件type.MediaItem.localFile.requestConcurrency100同時下載的圖片數(shù)量服務(wù)器崩潰時可調(diào)低production.allow404Images/production.allow401Imagesfalse允許返回 404/401 的圖片 URL 不使生產(chǎn)構(gòu)建失敗401 常用于保護(hù)內(nèi)容場景替代 404三、Gatsby Preview預(yù)覽問題排查3.1 Broken Preview templates預(yù)覽模板報錯被預(yù)覽的文章通常比開發(fā)時測試的數(shù)據(jù)少得多因此一旦模板訪問了不存在的字段預(yù)覽就會報錯。官方推薦的本地調(diào)試方案是讓預(yù)覽請求打到本地 Gatsby以刷新模式啟動本地 GatsbyENABLE_GATSBY_REFRESH_ENDPOINTtrue gatsby develop安裝 ngroknpm i -g ngrok新開終端窗口暴露本地 8000 端口ngrok http 8000在 WordPress 后臺的 GatsbyJS 設(shè)置中將 Preview 實例 URL 填為https://your-ngrok-url.ngrok.io預(yù)覽刷新端點填為https://your-ngrok-url.ngrok.io/__refresh。之后在wp-admin中點擊「預(yù)覽」就會使用本地 Gatsby 實例渲染。你可以在預(yù)覽 iframe 中檢查加載的是哪個 Gatsby 路徑并直接打開該路徑進(jìn)一步調(diào)試。預(yù)防建議在預(yù)覽模板中盡量使用可選鏈optional chaining避免對可能為undefined的屬性直接取值從源頭減少「數(shù)據(jù)缺失導(dǎo)致模板崩潰」的可能。3.2 Previews Dont Update預(yù)覽不更新檢查wp-config.php中是否禁用了文章修訂post revisions。如果存在下面這行請刪除它define( WP_POST_REVISIONS, FALSE );禁用文章修訂會導(dǎo)致 WPGraphQL 無法正確感知文章變更這是一個已知的 WPGraphQL 側(cè) bug相關(guān) issueWPGraphQL #1408。若站點已啟用修訂但預(yù)覽仍不更新請到 Gatsby 倉庫提交新 issue 并附上復(fù)現(xiàn)信息。3.3 Preview debug mode預(yù)覽調(diào)試模式開啟 Preview 調(diào)試模式可深入排查 Gatsby Preview 構(gòu)建過程。兩種開啟方式二選一在插件選項中啟用{ resolve: gatsby-source-wordpress, options: { debug: { preview: true, }, }, },設(shè)置環(huán)境變量WP_GATSBY_PREVIEW_DEBUGtrue開啟后終端會額外輸出三類信息發(fā)送給 Gatsby 進(jìn)程的webhook body 內(nèi)容Gatsby 接收到的Preview change events 列表Preview 期間拉取的node Preview 數(shù)據(jù)。配套調(diào)試選項開啟debug.preview后debug.graphql.printIntrospectionDiff也會被默認(rèn)啟用用于打印 schema 變更時新舊類型之間的差異默認(rèn)關(guān)閉。更多調(diào)試選項debug.timeBuildSteps、debug.throwRefetchErrors、debug.disableCompatibilityCheck等見 plugin-options.md。四、調(diào)試選項速查與底層原理4.1 常用調(diào)試配置一覽以下是本文涉及的調(diào)試相關(guān)插件選項默認(rèn)值均來自 declare-plugin-options-schema.js 中的 Joi schema配置項默認(rèn)值說明verbosetrue終端詳細(xì)日志節(jié)點拉取時顯示每個類型已拉取節(jié)點數(shù)debug.graphql.writeQueriesToDiskfalse將每個類型內(nèi)部生成的 GraphQL 查詢寫入./WordPress/GraphQL/[TypeName]/*.graphqldebug.graphql.showQueryOnErrorfalseGraphQL 請求出錯時把查詢打印到終端debug.graphql.showQueryVarsOnErrorfalse出錯時打印查詢變量debug.graphql.copyQueryOnErrorfalse出錯時把查詢復(fù)制到系統(tǒng)剪貼板受支持時debug.graphql.copyNodeSourcingQueryAndExitfalse填入遠(yuǎn)端 schema 的類型名后把該類型的節(jié)點拉取查詢復(fù)制到剪貼板并退出進(jìn)程debug.graphql.panicOnErrorfalse任一 GraphQL 錯誤都觸發(fā) panic默認(rèn)關(guān)閉因為有時錯誤會與有效數(shù)據(jù)一起返回debug.graphql.onlyReportCriticalErrorstrue只報告關(guān)鍵錯誤過濾伴隨有效數(shù)據(jù)一起返回的非關(guān)鍵錯誤debug.previewfalse輸出 Preview 進(jìn)程的額外信息debug.timeBuildStepsfalse顯示構(gòu)建各內(nèi)部步驟耗時debug.throwRefetchErrorsfalse開啟后gatsby develop期間數(shù)據(jù)更新報錯將直接使構(gòu)建失敗而非自動恢復(fù)debug.disableCompatibilityCheckfalse關(guān)閉對遠(yuǎn)端 WPGraphQL / WPGatsby 版本兼容性檢查僅建議調(diào)試使用4.2 底層請求鏈路可選進(jìn)階閱讀從 fetch-graphql.ts 的源碼結(jié)構(gòu)可以看出插件的請求韌性設(shè)計所有 GraphQL 請求經(jīng)由axios實例發(fā)出并使用axios-rate-limit按schema.requestConcurrency限制每秒請求數(shù)getHttp(limit)對 50x 系列錯誤自動重試async-retry最多 5 次其他錯誤則直接拋出對空字符串響應(yīng)、請求被重定向、響應(yīng) Content-Type 非application/json;如返回 HTML等異常分別給出專屬的錯誤提示與處理建議401Basic Auth 憑據(jù)缺失或錯誤、403防火墻/安全插件攔截、自簽名證書等場景均有專門的 panic 信息與修復(fù)指引。理解這條鏈路有助于你根據(jù)終端報錯的「錯誤碼與文案」快速判斷是配置問題、服務(wù)器問題還是 WPGraphQL 擴(kuò)展問題。五、總結(jié)一份可復(fù)用的排查路線圖數(shù)據(jù)缺失→ 先在 Gatsby 外對 WPGraphQL 直接執(zhí)行等價查詢不一致則開啟writeQueriesToDisk用落盤的node-list-query.graphql復(fù)現(xiàn)判定是 WPGraphQL 側(cè)還是插件側(cè)問題。GraphQL 報錯→ 借助writeQueriesToDisk拿到真實查詢在 Gatsby 外復(fù)現(xiàn)配合GRAPHQL_DEBUG、WP_DEBUG獲取更詳細(xì)錯誤。50x / 超時→ 下調(diào)schema.perPage、schema.requestConcurrency、schema.timeout的適當(dāng)組合用verbose測定服務(wù)器可承載并發(fā)數(shù)。媒體下載→ 控制localFile.requestConcurrency用maxFileSizeBytes/excludeByMimeTypes過濾文件并用文檔給出的 GraphQL 查詢核對被跳過的資源。預(yù)覽→ 本地ENABLE_GATSBY_REFRESH_ENDPOINTtrue gatsby develop ngrok 復(fù)現(xiàn)檢查WP_POST_REVISIONS開啟debug.preview或WP_GATSBY_PREVIEW_DEBUG觀察 webhook 與變更事件。掌握以上「先復(fù)現(xiàn)、再取證、后調(diào)參」的流程即可從容應(yīng)對 gatsby-source-wordpress 的大多數(shù)構(gòu)建與預(yù)覽問題。若需更多背景可繼續(xù)閱讀 getting-started.md、plugin-options.md 與 community-and-support.md并回到 README.md 總覽全貌?！久赓M下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址: https://gitcode.com/gh_mirrors/ga/gatsby創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 gatsby-source-wordpress 調(diào)試與故障排查完全指南：從節(jié)點數(shù)據(jù)缺失到媒體下載與預(yù)覽失效
gatsby-source-wordpress 調(diào)試與故障排查完全指南從節(jié)點數(shù)據(jù)缺失到媒體下載與預(yù)覽失效【免費下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址: https://gitcode.com/gh_mirrors/ga/gatsby導(dǎo)讀gatsby-source-wordpress是 Gatsby 生態(tài)中連接 WordPress經(jīng)由 WPGraphQL的核心數(shù)據(jù)源插件。本文以官方 debugging-and-troubleshooting.md 為骨架系統(tǒng)梳理節(jié)點數(shù)據(jù)缺失、GraphQL 報錯、WordPress 50x 錯誤、請求超時、媒體文件下載失敗/被跳過、Preview 模板損壞與預(yù)覽不更新等高頻問題的定位思路與修復(fù)手段并結(jié)合插件源碼fetch-graphql.ts、write-queries-to-disk.js、declare-plugin-options-schema.js解釋底層原理。讀完本文你將掌握一套可復(fù)制的「先在 Gatsby 外復(fù)現(xiàn)、再借助插件調(diào)試選項定位、最后針對性調(diào)整配置」的排查方法論。一、Node sourcing節(jié)點數(shù)據(jù)拉取階段的故障排查Node sourcing節(jié)點數(shù)據(jù)拉取是插件從 WPGraphQL 拉取 WordPress 內(nèi)容并轉(zhuǎn)化為 Gatsby 節(jié)點的核心階段絕大多數(shù)「數(shù)據(jù)不對、構(gòu)建報錯、構(gòu)建卡死」問題都發(fā)生在這個階段。下文按癥狀分類給出排查步驟。1.1 Gatsby 中數(shù)據(jù)缺失字段返回 null 或空數(shù)組當(dāng)某些字段在預(yù)期有值的情況下返回null或空數(shù)組時請按以下步驟定位第 1 步在 Gatsby 與 WPGraphQL 兩側(cè)分別執(zhí)行同一語義的查詢。使用第三方 GraphQL 客戶端如 GraphQL Playground直接對 WordPress 的 WPGraphQL 端點發(fā)查詢。注意不要使用 wp-graphiql 調(diào)試因為它帶有認(rèn)證態(tài)而 Gatsby 拉取數(shù)據(jù)時是不帶認(rèn)證的。例如 Gatsby 側(cè)查詢是這樣{ allWpPage { nodes { id title } } }那么在 WPGraphQL 端點直接執(zhí)行的等價查詢是{ pages { nodes { id title } } }第 2 步對比兩側(cè)返回數(shù)據(jù)。若兩邊返回的數(shù)據(jù)一致、但你認(rèn)為應(yīng)該有數(shù)據(jù)很可能問題出在 WPGraphQL 或你使用的 WPGraphQL 擴(kuò)展上。先回到 WordPress 后臺編輯對應(yīng)文章確認(rèn)這些字段確實有數(shù)據(jù)排除「數(shù)據(jù)本身就不存在」的可能。若兩側(cè)數(shù)據(jù)不一致進(jìn)入第 3 步啟用插件調(diào)試選項檢查插件內(nèi)部生成的查詢。第 3 步開啟writeQueriesToDisk調(diào)試選項。{ resolve: gatsby-source-wordpress, options: { debug: { graphql: { writeQueriesToDisk: true, }, }, }, }第 4 步重新運行g(shù)atsby develop或gatsby build。第 5 步查看落盤目錄。在你的 Gatsby 項目根目錄下會出現(xiàn)your-app/WordPress/GraphQL/其中為每個被拉取的節(jié)點類型各建一個子目錄。例如本例缺失標(biāo)題的類型是 Page則查看WordPress/GraphQL/Page/。第 6 步打開node-list-query.graphql并復(fù)制其中查詢。第 7 步把查詢粘貼到 GraphQL Playground并附帶查詢變量{ first: 100, after: null }第 8 步執(zhí)行并對比結(jié)果。結(jié)果同樣缺失數(shù)據(jù)說明這是 WPGraphQL 側(cè)或你使用的 WPGraphQL 擴(kuò)展的 bug。建議到 WPGraphQL 社區(qū)尋求幫助或到相應(yīng)擴(kuò)展倉庫提交 issue。為了幫助對方定位請逐個注釋掉復(fù)制出來的查詢里的字段二分排查出「哪一組字段組合」會觸發(fā)問題。常見根因提示如果你在使用 ACF 且在不同的字段組里給多個字段起了相同名稱極容易引發(fā)此類問題。找出沖突的字段名并重命名即可。結(jié)果數(shù)據(jù)完整說明是gatsby-source-wordpress自身的 bug請到 Gatsby 倉庫提交 issue 并附上復(fù)現(xiàn)信息。源碼佐證插件在啟動時會根據(jù)遠(yuǎn)端 schema 為每個可拉取類型生成 3 個查詢文件——node-list-query.graphql分頁列表、node-single-query.graphql單節(jié)點、node-preview-query.graphql預(yù)覽外加RootQuery/non-node-root-query.graphql非節(jié)點根字段。只有當(dāng)遠(yuǎn)端 schema 發(fā)生變更remoteSchema.schemaWasChanged時才會重新寫入寫入邏輯見 write-queries-to-disk.js。1.2 Node sourcing 階段的 GraphQL 報錯如果構(gòu)建因 GraphQL 請求返回的錯誤而終止終端輸出會明確指出報錯對應(yīng)的類型type。GraphQL 返回錯誤幾乎總是 WP 側(cè)的 bug。復(fù)現(xiàn)步驟如下同樣開啟debug.graphql.writeQueriesToDisk配置同上。重新運行g(shù)atsby develop或gatsby build。當(dāng)進(jìn)程因 GraphQL 錯誤退出時記下報錯對應(yīng)的 GraphQL 類型然后打開your-site/WordPress/GraphQL/[TypeOfErroringQuery]/node-list-query.graphql。該文件內(nèi)即為節(jié)點拉取時真實發(fā)送給 WPGraphQL 的查詢可據(jù)此在 Gatsby 之外復(fù)現(xiàn)錯誤、單獨調(diào)試。如何讓報錯信息更可讀從 fetch-graphql.ts 的報錯處理可以看到插件會盡力給出錯誤路徑形如mediaItems.nodes[55].mediaDetails.meta.focalLength、錯誤類別與行列號并提示若想獲得更詳細(xì)的錯誤消息可在wp-config.php中加入define( GRAPHQL_DEBUG, true );。1.3 WordPress 50x 錯誤500/502/503/504節(jié)點拉取階段遇到 50x 系列錯誤通常是以下兩種原因之一原因一單次查詢過重或并發(fā)過高壓垮了 WP 服務(wù)器。嘗試把schema.perPage從默認(rèn)的100調(diào)低例如 20~50減少單次請求拉取的節(jié)點數(shù)嘗試調(diào)低schema.requestConcurrency限制同一時刻發(fā)往 WPGraphQL 的并發(fā) GraphQL 請求數(shù)默認(rèn)值為15。原因二某條 GraphQL 查詢在 WP 服務(wù)器上觸發(fā)了不可恢復(fù)的 PHP 錯誤。這種情況請按 1.2 節(jié)的步驟復(fù)現(xiàn)并調(diào)試 GraphQL 錯誤。源碼佐證在 fetch-graphql.ts 中插件通過errorIs500ish識別 500/502/503/504并對 50x 錯誤自動重試最多 5 次retries: 5重試仍失敗后會以CODES.WordPress500ishError終止構(gòu)建并輸出「服務(wù)器可能過載」的提示與降低requestConcurrency/previewRequestConcurrency/perPage的配置建議。若錯誤為 500 且非重試可解決還會建議你在wp-config.php中開啟WP_DEBUG、WP_DEBUG_LOG、GRAPHQL_DEBUG后查看 WordPressdebug.log定位 PHP 錯誤。1.4 Node sourcing 超時節(jié)點拉取超時通常意味著你的 WP 服務(wù)器限制的并發(fā)請求數(shù)低于插件同時發(fā)起的請求數(shù)插件會同時為多個類型并發(fā)發(fā)請求。兩條解決路徑提升服務(wù)器能力調(diào)優(yōu)或更換服務(wù)器配置提高可承載的并發(fā)連接數(shù)降低插件并發(fā)把schema.requestConcurrency調(diào)到低于服務(wù)器可承載的并發(fā)數(shù)。如何測定服務(wù)器能承受多少并發(fā)開啟verbose選項{ resolve: gatsby-source-wordpress, options: { verbose: true, }, },重新構(gòu)建。終端會打印一長串插件正在拉取的類型Page、Post、User 等每行右側(cè)標(biāo)注了該類型已拉取的節(jié)點數(shù)。列表底部有一些尚未返回節(jié)點的類型。從「最后一個像被凍結(jié)住的類型」往列表頂部數(shù)數(shù)出來的數(shù)量大致就是服務(wù)器能承受的并發(fā) GraphQL 請求數(shù)。注意舊環(huán)境變量GATSBY_CONCURRENCT_DOWNLOAD已廢棄現(xiàn)在統(tǒng)一使用schema.requestConcurrency配置項。超時與構(gòu)建失敗的更多細(xì)節(jié)插件默認(rèn)請求超時為schema.timeout 30000毫秒超時后會以CODES.Timeout報錯退出并提示你檢查 URL 是否正確、是否需要提升服務(wù)器資源或降低perPage。相關(guān)實現(xiàn)見 fetch-graphql.ts。二、Media File Download媒體文件下載問題2.1 媒體文件下載錯誤服務(wù)器被壓垮媒體文件下載階段最主要的錯誤是并發(fā)請求過多導(dǎo)致遠(yuǎn)端服務(wù)器過載。gatsby-source-wordpress會把媒體文件下載與 GraphQL 數(shù)據(jù)拉取分開限制并發(fā)GraphQL 請求并發(fā)schema.requestConcurrency默認(rèn)15媒體文件下載并發(fā)type.MediaItem.localFile.requestConcurrency默認(rèn)100。遇到下載錯誤時把schema.requestConcurrency調(diào)到低于默認(rèn)值100注意該小節(jié)文檔語境下指媒體下載并發(fā)即localFile.requestConcurrency的場景再逐步實驗找到服務(wù)器能穩(wěn)定承載的「最大并發(fā)數(shù)」。若 WP 服務(wù)器在導(dǎo)入/構(gòu)建時崩潰優(yōu)先降低該值。2.2 媒體文件被跳過下載Skipped媒體文件未下載通常有兩大原因文件大小超過了type.MediaItem.localFile.maxFileSizeBytes配置上限默認(rèn)15728640字節(jié)即 15MB文件的 MIME 類型被列入了type.MediaItem.localFile.excludeByMimeTypes默認(rèn)[]即不排除任何類型。排查因maxFileSizeBytes被跳過的文件啟動gatsby develop執(zhí)行以下 GraphQL 查詢?? 務(wù)必將gt過濾器中的數(shù)字替換為你 gatsby 配置中maxFileSizeBytes的實際值query TOO_LARGE_FILES { allWpMediaItem(filter: { fileSize: { gt: 15728640 } }) { nodes { id sourceUrl fileSize } } }排查因excludeByMimeTypes被跳過的文件啟動gatsby develop執(zhí)行以下查詢?? 務(wù)必將in過濾器中的 MIME 類型數(shù)組替換為你配置中的實際值query MIME_TYPE_EXCLUDED { allWpMediaItem(filter: { mimeType: { in: [image/jpeg, video/mp4] } }) { nodes { id sourceUrl mimeType } } }相關(guān)配置速查詳見 plugin-options.md配置項默認(rèn)值作用type.MediaItem.localFile.excludeByMimeTypes[]按 MIME 類型阻止下載對應(yīng)文件type.MediaItem.localFile.maxFileSizeBytes1572864015MB阻止下載超過指定字節(jié)數(shù)的文件type.MediaItem.localFile.requestConcurrency100同時下載的圖片數(shù)量服務(wù)器崩潰時可調(diào)低production.allow404Images/production.allow401Imagesfalse允許返回 404/401 的圖片 URL 不使生產(chǎn)構(gòu)建失敗401 常用于保護(hù)內(nèi)容場景替代 404三、Gatsby Preview預(yù)覽問題排查3.1 Broken Preview templates預(yù)覽模板報錯被預(yù)覽的文章通常比開發(fā)時測試的數(shù)據(jù)少得多因此一旦模板訪問了不存在的字段預(yù)覽就會報錯。官方推薦的本地調(diào)試方案是讓預(yù)覽請求打到本地 Gatsby以刷新模式啟動本地 GatsbyENABLE_GATSBY_REFRESH_ENDPOINTtrue gatsby develop安裝 ngroknpm i -g ngrok新開終端窗口暴露本地 8000 端口ngrok http 8000在 WordPress 后臺的 GatsbyJS 設(shè)置中將 Preview 實例 URL 填為https://your-ngrok-url.ngrok.io預(yù)覽刷新端點填為https://your-ngrok-url.ngrok.io/__refresh。之后在wp-admin中點擊「預(yù)覽」就會使用本地 Gatsby 實例渲染。你可以在預(yù)覽 iframe 中檢查加載的是哪個 Gatsby 路徑并直接打開該路徑進(jìn)一步調(diào)試。預(yù)防建議在預(yù)覽模板中盡量使用可選鏈optional chaining避免對可能為undefined的屬性直接取值從源頭減少「數(shù)據(jù)缺失導(dǎo)致模板崩潰」的可能。3.2 Previews Dont Update預(yù)覽不更新檢查wp-config.php中是否禁用了文章修訂post revisions。如果存在下面這行請刪除它define( WP_POST_REVISIONS, FALSE );禁用文章修訂會導(dǎo)致 WPGraphQL 無法正確感知文章變更這是一個已知的 WPGraphQL 側(cè) bug相關(guān) issueWPGraphQL #1408。若站點已啟用修訂但預(yù)覽仍不更新請到 Gatsby 倉庫提交新 issue 并附上復(fù)現(xiàn)信息。3.3 Preview debug mode預(yù)覽調(diào)試模式開啟 Preview 調(diào)試模式可深入排查 Gatsby Preview 構(gòu)建過程。兩種開啟方式二選一在插件選項中啟用{ resolve: gatsby-source-wordpress, options: { debug: { preview: true, }, }, },設(shè)置環(huán)境變量WP_GATSBY_PREVIEW_DEBUGtrue開啟后終端會額外輸出三類信息發(fā)送給 Gatsby 進(jìn)程的webhook body 內(nèi)容Gatsby 接收到的Preview change events 列表Preview 期間拉取的node Preview 數(shù)據(jù)。配套調(diào)試選項開啟debug.preview后debug.graphql.printIntrospectionDiff也會被默認(rèn)啟用用于打印 schema 變更時新舊類型之間的差異默認(rèn)關(guān)閉。更多調(diào)試選項debug.timeBuildSteps、debug.throwRefetchErrors、debug.disableCompatibilityCheck等見 plugin-options.md。四、調(diào)試選項速查與底層原理4.1 常用調(diào)試配置一覽以下是本文涉及的調(diào)試相關(guān)插件選項默認(rèn)值均來自 declare-plugin-options-schema.js 中的 Joi schema配置項默認(rèn)值說明verbosetrue終端詳細(xì)日志節(jié)點拉取時顯示每個類型已拉取節(jié)點數(shù)debug.graphql.writeQueriesToDiskfalse將每個類型內(nèi)部生成的 GraphQL 查詢寫入./WordPress/GraphQL/[TypeName]/*.graphqldebug.graphql.showQueryOnErrorfalseGraphQL 請求出錯時把查詢打印到終端debug.graphql.showQueryVarsOnErrorfalse出錯時打印查詢變量debug.graphql.copyQueryOnErrorfalse出錯時把查詢復(fù)制到系統(tǒng)剪貼板受支持時debug.graphql.copyNodeSourcingQueryAndExitfalse填入遠(yuǎn)端 schema 的類型名后把該類型的節(jié)點拉取查詢復(fù)制到剪貼板并退出進(jìn)程debug.graphql.panicOnErrorfalse任一 GraphQL 錯誤都觸發(fā) panic默認(rèn)關(guān)閉因為有時錯誤會與有效數(shù)據(jù)一起返回debug.graphql.onlyReportCriticalErrorstrue只報告關(guān)鍵錯誤過濾伴隨有效數(shù)據(jù)一起返回的非關(guān)鍵錯誤debug.previewfalse輸出 Preview 進(jìn)程的額外信息debug.timeBuildStepsfalse顯示構(gòu)建各內(nèi)部步驟耗時debug.throwRefetchErrorsfalse開啟后gatsby develop期間數(shù)據(jù)更新報錯將直接使構(gòu)建失敗而非自動恢復(fù)debug.disableCompatibilityCheckfalse關(guān)閉對遠(yuǎn)端 WPGraphQL / WPGatsby 版本兼容性檢查僅建議調(diào)試使用4.2 底層請求鏈路可選進(jìn)階閱讀從 fetch-graphql.ts 的源碼結(jié)構(gòu)可以看出插件的請求韌性設(shè)計所有 GraphQL 請求經(jīng)由axios實例發(fā)出并使用axios-rate-limit按schema.requestConcurrency限制每秒請求數(shù)getHttp(limit)對 50x 系列錯誤自動重試async-retry最多 5 次其他錯誤則直接拋出對空字符串響應(yīng)、請求被重定向、響應(yīng) Content-Type 非application/json;如返回 HTML等異常分別給出專屬的錯誤提示與處理建議401Basic Auth 憑據(jù)缺失或錯誤、403防火墻/安全插件攔截、自簽名證書等場景均有專門的 panic 信息與修復(fù)指引。理解這條鏈路有助于你根據(jù)終端報錯的「錯誤碼與文案」快速判斷是配置問題、服務(wù)器問題還是 WPGraphQL 擴(kuò)展問題。五、總結(jié)一份可復(fù)用的排查路線圖數(shù)據(jù)缺失→ 先在 Gatsby 外對 WPGraphQL 直接執(zhí)行等價查詢不一致則開啟writeQueriesToDisk用落盤的node-list-query.graphql復(fù)現(xiàn)判定是 WPGraphQL 側(cè)還是插件側(cè)問題。GraphQL 報錯→ 借助writeQueriesToDisk拿到真實查詢在 Gatsby 外復(fù)現(xiàn)配合GRAPHQL_DEBUG、WP_DEBUG獲取更詳細(xì)錯誤。50x / 超時→ 下調(diào)schema.perPage、schema.requestConcurrency、schema.timeout的適當(dāng)組合用verbose測定服務(wù)器可承載并發(fā)數(shù)。媒體下載→ 控制localFile.requestConcurrency用maxFileSizeBytes/excludeByMimeTypes過濾文件并用文檔給出的 GraphQL 查詢核對被跳過的資源。預(yù)覽→ 本地ENABLE_GATSBY_REFRESH_ENDPOINTtrue gatsby develop ngrok 復(fù)現(xiàn)檢查WP_POST_REVISIONS開啟debug.preview或WP_GATSBY_PREVIEW_DEBUG觀察 webhook 與變更事件。掌握以上「先復(fù)現(xiàn)、再取證、后調(diào)參」的流程即可從容應(yīng)對 gatsby-source-wordpress 的大多數(shù)構(gòu)建與預(yù)覽問題。若需更多背景可繼續(xù)閱讀 getting-started.md、plugin-options.md 與 community-and-support.md并回到 README.md 總覽全貌?！久赓M下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址: https://gitcode.com/gh_mirrors/ga/gatsby創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考