{"record":{"id":"f51cc9f60208447b","repo":"docmirror/dev-sidecar","slug":"key-f51cc9","errorCode":null,"errorMessage":"插件【${key}】不可用，已注册为禁用状态","messagePattern":"插件【(.+?)】不可用，已注册为禁用状态","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/core/src/expose.js","lineNumber":36,"sourceCode":"function setupPlugin (key, plugin, context, config) {\n  const pluginConfig = plugin.config\n  const PluginClass = plugin.plugin\n  const pluginStatus = plugin.status\n  const api = PluginClass(context)\n  config.addDefault(key, pluginConfig)\n  if (pluginStatus) {\n    lodash.set(status, key, pluginStatus)\n  }\n  return api\n}\n\nconst proxy = setupPlugin('proxy', modules.proxy, context, config)\nconst plugin = {}\nfor (const key in modules.plugin) {\n  const target = modules.plugin[key]\n  if (target == null) {\n    // 插件不可用（如 SEA 独立可执行文件中无法携带 free-eye），注册为禁用状态\n    log.warn(`插件【${key}】不可用，已注册为禁用状态`)\n    const stub = {\n      config: { key, enabled: false },\n      status: { enabled: false },\n      plugin: () => ({\n        start: async () => log.warn(`插件【${key}】不可用，无法启动`),\n        stop: async () => {},\n        close: async () => {},\n        run: async () => { throw new Error(`插件【${key}】不可用`) },\n      }),\n    }\n    const stubApi = setupPlugin(`plugin.${key}`, stub, context, config)\n    plugin[key] = stubApi\n    continue\n  }\n  const api = setupPlugin(`plugin.${key}`, target, context, config)\n  plugin[key] = api\n}\nconfig.resetDefault()","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/core/src/expose.js#L18-L54","documentation":"Warning logged in expose.js during startup when a plugin module from modules.plugin resolved to null/undefined. This happens because the getter for a plugin (e.g. free_eye) failed to load and returned null (commonly in SEA single-executable builds where the ESM free-eye module cannot be bundled). The core registers a disabled stub plugin in its place so the app still starts: its config/status are enabled:false and start/stop are no-ops.","triggerScenarios":"Application startup (expose.js module init) with a plugin key whose module getter returned null — specifically the free_eye getter in modules/plugin/index.js catching a require() failure, e.g. running from a Node SEA build where ./free-eye (ESM) cannot be required.","commonSituations":"Running the dev-sidecar SEA standalone executable where free-eye is not packaged; a broken install where the free-eye directory/dependencies are missing; a module that throws at require-time due to a syntax/dependency error, silently degrading the plugin to disabled.","solutions":["If you don't need the plugin (e.g. free-eye in a headless/SEA build), ignore the warning — behavior is intentional and safe.","If you need it, run from a normal Node install (pnpm install at repo root) rather than the SEA executable so the ESM module is present.","Verify packages/core/src/modules/plugin/free-eye exists and its dependencies are installed; reinstall/repair the package if missing.","If a custom plugin getter returns null, fix the underlying require() error (check logs for the companion '加载 free-eye 插件失败' message with e.message)."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const mod = DevSidecar.modules?.plugin?.[key]\nif (mod == null) {\n  console.warn(`plugin ${key} unavailable, skipping registration/start`)\n}","typeGuard":"function isPluginAvailable(mod) {\n  return mod != null && typeof mod === 'object' && mod.plugin != null\n}","tryCatchPattern":"try {\n  await plugin.start(key)\n} catch (e) {\n  if (/不可用/.test(e.message)) console.warn(`plugin ${key} unavailable, ignored:`, e.message)\n  else throw e\n}","preventionTips":["Check plugin status.enabled before starting a plugin.","For SEA builds, treat free-eye and similar ESM-only plugins as optional.","Keep full pnpm install for environments where all plugins are needed.","Watch startup logs for '插件不可用' warnings to know which plugins are stubbed."],"tags":["plugin","sea","degraded-mode","startup"],"backgroundTag":"plugin-module-unavailable","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}