Dev Proxy 故障排除

請參考本指南來診斷並修正常見的開發代理問題。 從你的症狀開始，逐步探討診斷問題，找到解決方案。

症狀：Dev Proxy 未攔截到請求

你啟動了 Dev Proxy，但你的應用程式請求沒有出現在 Dev Proxy 輸出中。 透過這些問題找出原因。

Dev Proxy 有在執行嗎？

檢查 Dev Proxy 是否在執行並準備好攔截請求。

應該注意哪些事項：

啟動 Dev Proxy 後，你應該會看到類似的輸出：

 info    Dev Proxy API listening on http://127.0.0.1:8897...
 info    Dev Proxy listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

如果你沒看到這個輸出：

  • 正確安裝開發代理的情況，可以透過執行 devproxy --version 來檢查。
  • 如果出現錯誤，請 重新安裝 Dev Proxy

Dev Proxy 有註冊為系統代理嗎？

開發代理必須註冊為系統代理，才能自動攔截請求。 如果不是，你的應用程式請求會完全地繞過Dev Proxy。

如何檢查 macOS：

  1. 開放 系統設定>網路
  2. 選擇主動網路連線
  3. 前往 詳情...>代理
  4. 尋找設為127.0.0.1:8000的安全 HTTP 代理（HTTPS）。

如何在 Windows 上檢查：

  1. 開啟 Settings>網路與網際網路>代理
  2. 在 手動代理設定中，檢查代理伺服器是否設定為 127.0.0.1:8000

如果開發代理沒有註冊為系統代理：

檢查您的開發代理伺服器設定。 執行 devproxy config 開啟設定檔，確認其中不包含：

{
  "asSystemProxy": false
}

如果這個設定存在且設定為 false，則移除或設為 true，請重新啟動開發代理。

你有注意正確的網址嗎？

開發代理僅攔截符合設定中模式的 urlsToWatch URL 請求。

如何檢查：

  1. 檢查開發代理伺服器啟動時的輸出結果，查看被追蹤的網址清單。
  2. 將它們與應用程式呼叫的網址做比較

常見問題：

  • 缺少萬用符號： https://api.example.com 不符合 https://api.example.com/users。 請改用 https://api.example.com/*。
  • 錯誤網域：請仔細檢查網域名稱，包括子網域
  • HTTP 與 HTTPS：確保協定相符

要測試你的網址模式：

devproxy --urls-to-watch "https://your-api.com/*"

然後向你的 API 提出請求，檢查 Dev Proxy 是否會記錄。

你有使用正確的設定檔嗎？

Dev Proxy 可能使用的設定檔和你預期的不一樣。

Dev Proxy 如何找到設定檔：

  1. 如果你指定 --config-file，開發代理會使用該檔案
  2. 否則，Dev Proxy會在目前目錄中尋找devproxyrc.json
  3. 如果找不到，Dev Proxy 會使用預設設定

要確認使用的是哪個設定檔：

執行 Dev Proxy 並啟用偵錯日誌：

devproxy --log-level debug

查看輸出，以確定載入了哪個設定檔案。

要明確指定一個設定檔：

devproxy --config-file ./my-config.json

你是用 Dev Proxy 搭配 Node.js 應用程式嗎？

Node.js 不會自動使用系統代理設定。 你需要設定你的 Node.js 應用程式明確使用代理伺服器。

Solution:

使用 global-agent 套件或設定你的 HTTP 函式庫來使用代理伺服器。 詳細說明請參閱「 使用 Dev Proxy 搭配 Node.js 應用程式 」。

用 global-agent 快速解決：

  1. 安裝 global-agent：

    npm install global-agent

  2. 新增應用程式的入口：

    import { bootstrap } from 'global-agent';
bootstrap();

  3. 用代理環境變數啟動你的應用程式：

    NODE_TLS_REJECT_UNAUTHORIZED=0 GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8000 node app.js

你是在 Windows 上使用 Dev Proxy 搭配 PowerShell 嗎？

PowerShell 不會自動使用系統代理設定來處理使用 Invoke-WebRequest or Invoke-RestMethod的網頁請求。

Solution:

透過設定 -Proxy 參數設定 PowerShell 來使用代理伺服器：

Invoke-WebRequest -Uri "https://api.example.com/data" -Proxy "http://127.0.0.1:8000"

或者設定整個會話的代理：

$env:HTTPS_PROXY = "http://127.0.0.1:8000"
$env:HTTP_PROXY = "http://127.0.0.1:8000"

如果你使用 PowerShell 7+，也可以使用：

[System.Net.WebRequest]::DefaultWebProxy = New-Object System.Net.WebProxy("http://127.0.0.1:8000")

其他平台與框架

如果你使用其他平台，請參考以下指南：

平台 Guide
.NET 應用程式 在 .NET 應用程式中使用 Dev Proxy
.NET 4.8 應用程式 .NET 4.8 應用程式需要特殊設定
Docker 容器 在 Docker 容器中使用 Dev Proxy
SharePoint 框架 使用 Dev Proxy 搭配 SPFx

症狀：請求被攔截但依然原樣通過

Dev Proxy 會在輸出中顯示你的請求，但這些請求並未被修改、模擬，也沒有回傳模擬錯誤。

你的插件有啟用嗎？

確認你想使用的插件是否已啟用。

如何檢查：

打開你的設定檔，確認：

  1. 外掛會列在 plugins 陣列中
  2. 這個插件有 "enabled": true
{
  "plugins": [
    {
      "name": "GenericRandomErrorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    }
  ]
}

你的插件順序正確嗎？

插件順序在 Dev Proxy 中很重要。 插件會依照列出的順序執行，有些插件可能會在其他執行前停止處理。

常見問題：

如果你在MockResponsePlugin之前有GenericRandomErrorPlugin，且模擬物符合你的請求，隨機錯誤外掛就不會執行。

Solution:

依照你想要的順序安排插件處理請求。 更多資訊，請參見 為什麼使用 mock 時不會拋出隨機錯誤？

你的模擬網址模式是否符合請求？

對於模擬回應，URL 模式必須與請求 URL 完全一致。

需要注意的事項：

  • 查詢字串參數： https://api.example.com/users?id=1 不匹配 https://api.example.com/users
  • 尾部劃痕： https://api.example.com/users/ 不符 https://api.example.com/users
  • 大小寫敏感性：URL 路徑對大小寫有區分

請求方式正確嗎？

模擬考是針對特定方法的。 模擬 GET 請求與 POST 請求不匹配。

如何檢查：

在你的模擬檔案中，請確認 method 該物業符合你的要求：

{
  "request": {
    "url": "https://api.example.com/users",
    "method": "GET"
  },
  "response": {
    "statusCode": 200,
    "body": { "users": [] }
  }
}

症狀：你的應用程式出現 SSL/憑證錯誤

你的應用程式在嘗試透過 Dev Proxy 發出請求時會跳出 SSL 或憑證錯誤。

你有安裝 Dev Proxy 憑證嗎？

Dev Proxy 使用自簽憑證來解密 HTTPS 流量。 你的系統必須信任這份憑證。

Solution:

執行憑證安裝指令：

devproxy cert ensure

這個指令會安裝並信任你的系統上的開發代理憑證。

這張證書值得信賴嗎？

憑證可能已安裝但不被信任。

如何檢查 macOS：

  1. 開放 鑰匙圈存取
  2. 搜尋「Dev Proxy」
  3. 雙擊該證書
  4. 擴展 信任
  5. 確認安全套接層（SSL）是否設定為「始終信任」

如何在 Windows 上檢查：

  1. certmgr.msc執行
  2. 導航至 受信任根認證機構>憑證
  3. 請尋找 Dev Proxy 證書

如果憑證不被信任：

移除並重新安裝憑證：

devproxy cert remove
devproxy cert ensure

你有在用 Node.js嗎？

Node.js 預設不會使用系統憑證儲存。 你需要以下其中一項：

選項一：停用憑證驗證（僅限開發階段）：

NODE_TLS_REJECT_UNAUTHORIZED=0 node app.js

警告

請勿在生產環境中使用NODE_TLS_REJECT_UNAUTHORIZED=0。 它會關閉所有憑證驗證功能。

選項二：將開發代理憑證加入 Node.js：

匯出開發代理憑證並設定 NODE_EXTRA_CA_CERTS 環境變數：

NODE_EXTRA_CA_CERTS=/path/to/devproxy-cert.pem node app.js

你用的是不同的執行環境或框架嗎？

不同平台對憑證的處理方式不同：

平台 Solution
Python 使用 REQUESTS_CA_BUNDLE 或 SSL_CERT_FILE 環境變數
JAVA 將憑證匯入 Java 金鑰庫，使用 keytool
.NET 憑證通常透過系統儲存庫被信任
Docker 掛載憑證並在容器中更新 CA 憑證

其他常見問題

所有請求皆因閘道逾時而失敗

原因：

Dev Proxy 無法連到目標 API。

Solution:

請查看為什麼所有請求都因閘道逾時而失敗？

使用 Dev Proxy 後無法連線

原因：

Dev Proxy 並沒有正確地註銷為系統代理。

Solution:

請參考 ：為什麼使用代理伺服器後我的網路連線無法使用？

意外收到429個回應

原因：

已啟用並設定速率限制插件。

Solution:

你看 ，為什麼我一直收到429個回應？

資料庫錯誤

錯誤 Solution
SqliteConnection 初始化錯誤 修正 SQLite 設定
「資料庫磁碟映像檔格式錯誤」 重建資料庫

尋求更多幫助

如果你找不到解決方法：

  1. 啟用除錯日誌：執行 devproxy --log-level debug 以取得詳細輸出
  2. 搜尋現有問題： Dev Proxy GitHub 問題
  3. 尋求幫助： 尋求幫助與支持

另請參閱

  • 上次更新時間：