檢查規則
nginx-ui plugin lint 和 nginx-ui plugin conformance 回報的每個問題都附帶它違反的規則名稱。本頁解釋每一條規則，並連結到指南中的相關內容。
- lint 規則根據外掛目錄或外掛套件中的檔案檢查。error 會阻止外掛套件安裝；warning 指出安裝外掛的人會注意到的問題。
- conformance 規則透過執行外掛來檢查。每個測試案例的結果為通過、失敗，或在不適用時略過。
清單
manifest-json
lint errorplugin.json 缺少，或不是單一 JSON 物件。參見清單檔案。
manifest-id
lint errorid 缺少、超過 64 個字元，或不是 io.github.example.mydns 這樣以點分隔的小寫 ID。參見命名規則。
manifest-name
lint errorname 缺少或為空。
manifest-version
lint errorversion 缺少，或不是語意化版本。
manifest-api-version
lint errorapi_version 缺少，或不是 Nginx UI 實作的協定世代。參見版本與相容性。
manifest-parts
lint error清單沒有宣告 server、webapp 和 content 中的任何一個，外掛什麼也不會安裝。
manifest-icon
lint erroricon_path 不是安全的相對路徑。
manifest-i18n
lint error warningi18n 的某個鍵不是 zh_CN 這樣的語言代碼時為錯誤；執行檢查工具的 Nginx UI 沒有該語言時為警告，這時它顯示英文。參見清單檔案。
manifest-requires
lint errorrequires 中某一項的外掛 ID 無效。參見相依與衝突。
manifest-conflicts
lint errorconflicts 中某一項不是有效的外掛 ID、是外掛自己的 ID、重複出現，或同時出現在 requires 中。參見相依與衝突。
manifest-permissions
lint error warning未知權限為錯誤，重複列出的權限為警告。參見權限與安全。
manifest-permission-reasons
lint errorpermission_reasons 或 i18n 中它的翻譯裡，某個鍵不是 permissions 中的一項，或者原因超過 300 個字元。參見說明權限用途。
manifest-screenshots
lint errorscreenshots 超過 8 張；某個 id 缺少、格式不對或者重複；某個路徑缺少、不是安全的相對路徑、不是 PNG、JPEG 或 WebP 圖片，或者重複出現；某則說明超過 200 個字元；或者 i18n 的 screenshot_captions 中某個鍵不是螢幕截圖的 id。參見螢幕截圖。
capability-name
lint error某個能力名稱不是 Nginx UI 認識的能力。參見清單檔案。
capability-duplicate
lint error某個能力被列出了兩次。
server-entry
lint errorserver 既沒有 executables 也沒有 command。參見伺服器端進程。
server-command
lint errorserver.command 的第一個元素為空。
server-lifecycle
lint errorserver.lifecycle 不是 resident 或 on_demand。
server-idle-timeout
lint errorserver.idle_timeout_seconds 為負數。
server-paths
lint error warning可執行檔路徑，或包含分隔符號的 command 第一個元素不是安全的相對路徑時為錯誤；在執行檢查工具的機器上，command 指定的程式在 PATH 中找不到時為警告。
server-resources
lint errorserver.resources 的某個值為負數。參見資源。
settings-key
lint error某個設定欄位沒有鍵，或兩個欄位使用了同一個鍵。參見設定。
settings-type
lint error warning欄位型別未知，或 list 的預設值不是字串陣列時為錯誤；預設值與型別不符時為警告。
settings-options
lint errorselect 欄位沒有選項。
event-permission
lint warning訂閱了 log.paths_changed 卻沒有 log.files 權限，因此該事件永遠不會送達。參見宿主 API。
reserved-namespace
lint warningID 使用了保留給 Nginx UI 專案的 com.nginxui.*。參見命名規則。
network-permission
lint warning與服務商或目標通訊的能力沒有宣告 network 權限。參見權限與安全。
unused-permission
lint warning請求了只有外掛未宣告的能力才會用到的權限，例如沒有 mcp 能力卻請求 mcp。
外掛套件
package-file-name
lint warning外掛套件檔名中的 ID 或版本與清單不一致。參見命名規則。
package-layout
lint errorplugin.json 既不在封存檔根目錄，也不在一層目錄之下，或者封存檔無法讀取。參見打包。
package-paths
lint error某個封存檔項目不是安全的相對路徑。
package-links
lint error封存檔中包含符號連結或硬連結。
package-escape
lint error某個項目會被解壓縮到外掛目錄之外。
package-entries
lint error外掛套件的項目超過 10,000 個。參見限制。
package-size
lint error外掛套件中的檔案解壓縮後超過 256 MiB。
package-docs
lint error warning缺少 README.md 時為錯誤；缺少 LICENSE，或者 README 缺少應有的章節時為警告。參見打包。
package-executables
lint error warningserver.executables 或 server.command 宣告的檔案缺少或不是一般檔案時為錯誤；缺少執行權限時為警告。參見可執行檔。
package-platform
lint error單一平台的外掛套件沒有在 server.executables 中恰好只宣告自己的平台。參見單一平台的外掛套件。
簽章
signature-sums
lint errorplugin.sums 不符合規定的格式。參見手動簽章。
signature-files
lint warningplugin.sums 和 plugin.sums.minisig 只有一個，因此外掛套件被視為未簽章。
signature-mismatch
lint errorplugin.sums 與檔案不符：列出的檔案缺少或 SHA-256 不同，或者有檔案沒有列出。外掛套件在簽章後被修改過，永遠無法安裝。參見 Nginx UI 如何檢查外掛套件。
signature-signer
lint warning簽章無法用檢查工具已知的金鑰驗證：專案的官方外掛簽章金鑰，或外掛套件中帶有有效憑證的合作夥伴金鑰。對於社群外掛這是預期的，因為它的金鑰只由外掛目錄或維運人員指定。參見信任等級。
partner-files
lint warningplugin.partner 和 plugin.partner.minisig 只有一個，因此外掛套件沒有合作夥伴憑證。參見合作夥伴外掛。
partner-comment
lint warning合作夥伴憑證無法驗證：plugin.partner 不是公鑰，沒有官方外掛簽章金鑰為它簽章，或者可信註解的格式錯誤。
partner-certificate
lint warning合作夥伴憑證已到期，或者 plugin.sums.minisig 不是由憑證指定的金鑰簽署的，因此憑證對外掛套件不起作用。
signer-files
lint warning外掛套件中只有 plugin.signer 和 plugin.signer.minisig 之一，因此簽章金鑰憑證被忽略。參見簽章金鑰。
signer-certificate
lint warning簽章金鑰憑證無法解析、可信註解指明的不是外掛套件本身的外掛，或者 plugin.sums.minisig 不是由憑證指定的金鑰簽署的，因此憑證對外掛套件不起作用。lint 不知道主金鑰，憑證由誰簽發由外掛目錄和 Nginx UI 檢查。參見簽章金鑰。
協定與生命週期
protocol-stderr
conformance外掛把日誌寫到標準錯誤。參見通訊協定。
protocol-notification
conformance未知方法的通知不會得到回覆，且連線仍然可用。參見訊息。
protocol-concurrency
conformance20 個並行的 plugin.ping 呼叫全部得到回覆。
protocol-errors
conformance外掛沒有的方法回覆 -32601，格式錯誤的參數回覆 -32602 或 -32000，而不是停滯。參見錯誤碼。
protocol-grpc
conformance外掛回報的 gRPC 端點接受連線並回覆 plugin.ping。參見 gRPC 傳輸。
protocol-transports
conformance同一個呼叫透過標準輸入輸出和透過 gRPC 得到相同的結果或錯誤。兩種傳輸方式都測試過時才執行。
lifecycle-handshake
conformance交握在時間限制內完成。參見生命週期。
lifecycle-api-version
conformance交握回報的協定世代與 Nginx UI 實作的一致。
lifecycle-capabilities
conformance交握回報的能力與清單完全一致。
lifecycle-ping
conformanceplugin.ping 得到回覆。參見健康檢查。
lifecycle-shutdown
conformanceplugin.shutdown 和 plugin.exit 能及時停止進程。參見停止。
網頁介面
webapp-paths
lint errorwebapp.bundle_path 或 webapp.style_path 不是安全的相對路徑。參見瀏覽器套件。
webapp-pages
lint error某個頁面沒有 path，或其 file 不是安全的相對路徑。參見靜態頁面。
webapp-chunks
lint error宣告了 webapp.chunks 卻沒有 bundle_path，或者某個分塊的名稱或路徑無效、指向瀏覽器套件本身、與其他分塊共用路徑，或指向缺少的檔案。參見分塊。
webapp-bundle
lint conformance瀏覽器套件檔案存在，並且是 Nginx UI 可以載入的指令碼。參見建置。
webapp-register
conformance瀏覽器套件用清單 ID 註冊自己。參見註冊外掛。
webapp-chunk-files
lint conformance分塊檔案為空或缺少時為錯誤；位於 Nginx UI 提供瀏覽器套件的目錄之外時為警告。
DNS-01
dns01-block
lint error宣告了 dns01 能力卻沒有服務商。參見 DNS-01。
dns01-code
lint error服務商代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
dns01-name
lint error服務商沒有名稱。
dns01-form
lint error服務商沒有 form，或者表單違反了認證表單的規則：欄位沒有鍵或標籤、鍵重複、group 或 unit 未知、只有一種登入方式、方式名稱重複、方式列出了非認證欄位、values 的鍵使用不當、兩種方式完全相同，或者有多個推薦方式。
dns01-present
conformancedns01.present 對第一個服務商有回覆。
dns01-validate
conformancedns01.validate 對空設定的回覆符合預期。
dns01-options
conformancedns01.options 有回覆，或回覆 -32002。
dns01-check
conformancedns01.check 有回覆，或回覆 -32002。
HTTP 介面
http-block
lint error宣告了 http 能力卻沒有 http 區塊，或者 listen 不是 unix 或 rpc。參見 HTTP 介面。
設定表單
configuration-fields
lint errorconfiguration 表單中的某個欄位沒有鍵、鍵重複、型別未知或沒有 display_name。參見設定表單。
通知通道
notify-block
lint error宣告了 notify 能力卻沒有通道。參見通知通道。
notify-code
lint error通道代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
notify-name
lint error通道沒有名稱。
notify-validate
conformancenotify.validate 對空設定回覆指出必填欄位的 -32003，或者在通道沒有必填欄位時回覆 {}。測試從不呼叫 notify.send，因為它會存取真實服務。
健康檢查
probe-block
lint error宣告了 probe 能力卻沒有類型。參見健康檢查。
probe-code
lint error類型代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
probe-kind
lint error類型沒有名稱，或其設定表單無效。
probe-check
conformance對無法連線的目標執行第一個類型的 probe.check，能夠及時回覆。
probe-result
conformance回覆包含已知的 status 和非負的 latency_ms，或者是指出欄位的 -32003。
MCP 工具
mcp-block
lint error宣告了 mcp 能力卻沒有工具，或沒有 mcp 權限。參見 MCP 工具。
mcp-tool
lint error工具名稱不符合 ^[a-z0-9][a-z0-9_-]{0,47}$、被宣告了兩次，或者工具沒有描述。
mcp-input-schema
lint errorinput_schema 的 type 不是 object。
mcp-unknown-tool
conformance呼叫清單未宣告的工具會得到 -32602。測試不會呼叫任何已宣告的工具，因為它們可能改變狀態。
儲存
storage-block
lint error宣告了 storage 能力卻沒有後端。參見儲存。
storage-code
lint error後端代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
storage-backend
lint error後端沒有名稱，或其設定表單無效。
storage-list
conformance使用空設定的 storage.list 能及時回覆，結果為指出必填欄位的 -32003 或一份清單。測試不會儲存、取回或刪除任何內容。
storage-validate
conformancestorage.validate 對空設定回覆指出必填欄位的 -32003，或回覆 {}。
憑證部署
deploy-block
lint error宣告了 cert.deploy 能力卻沒有目標，或沒有 cert.deploy 權限。參見憑證部署。
deploy-code
lint error目標代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
deploy-target
lint error目標沒有名稱，或其設定表單無效。
deploy-dry-run
conformance對一張臨時憑證的試執行推送能及時回覆。測試從不進行真正的推送。
deploy-validate
conformancedeploy.validate 對空設定回覆指出必填欄位的 -32003，或回覆 {}。
封鎖清單
blocklist-block
lint error宣告了 security.blocklist 能力卻沒有來源，或沒有 network 權限。參見封鎖清單。
blocklist-code
lint error來源代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
blocklist-source
lint error來源沒有名稱、設定表單無效，或者 refresh_seconds 介於 1 到 59 之間或為負數。
blocklist-fetch
conformance使用空設定的 blocklist.fetch 能及時回覆，且項目中的位址都能解析。
blocklist-errors
conformance需要設定的來源回覆指出欄位的 -32003，而不是空清單。
上游探索
discovery-block
lint error宣告了 upstream.discovery 能力卻沒有提供者，或沒有 network 權限。參見上游探索。
discovery-code
lint error提供者代碼不符合 ^[a-z0-9-]{2,32}$，或被宣告了兩次。
discovery-provider
lint error提供者沒有名稱，或其設定表單無效。
discovery-resolve
conformance使用空設定的 discovery.resolve 能及時回覆，且目標的連接埠都在 1 到 65535 之間。
discovery-errors
conformance需要設定的提供者或未知的服務回覆指出欄位的 -32003。
存取日誌串流
log-sink-permission
lint error宣告了 log.sink 能力卻沒有 log.read 權限。參見存取日誌串流。
log-sink-block
lint warning有 log_sink 區塊卻沒有 log.sink 能力，該區塊不起作用。
log-sink-batch
lint errorbatch_size 不在 0 到 4096 之間，或者 flush_interval_ms 介於 1 到 49 之間或為負數。
log-sink-formats
lint error格式不是 combined 或 raw，或被列出了兩次。
log-sink-transport
conformance透過標準輸入輸出傳送的 log.push 得到 -32601，並且外掛提供 gRPC。
log-sink-push
conformance包含三個項目的串流能及時得到 accepted 為 3 的回覆。只測試標準輸入輸出時略過。
範本與翻譯
content-paths
lint errorcontent.templates 或 content.locales 不是安全的相對路徑。參見範本與翻譯。
content-without-server
lint error沒有 server 的清單宣告了 capabilities、cron 或 events，而它們都需要進程。
content-templates
lint error warning範本目錄缺少、不是目錄，或者 conf/ 和 block/ 中都沒有範本時為錯誤；有不是範本的項目時為警告。參見範本。
content-template
lint error warning範本無法解析或無法用預設值渲染時為錯誤；沒有 name 時為警告。
content-locales
lint error warning翻譯目錄缺少、沒有 .po 檔案，或者有檔名不是語言代碼的檔案時為錯誤；有執行檢查工具的 Nginx UI 沒有的語言的檔案，或者有其他項目時為警告。參見翻譯。
content-locale
lint error某個翻譯檔案無法解析。