易错点清单

这一页是「改代码前必读」。以下问题都曾出现过，改动时勿回退。

框架行为

日志回环：core/logger 用 attachLogger + echoing 护栏。不要改回 attachConsole，也不要让 console 接管函数在回显期转发日志——会无限循环。
keepAlive：MainLayout 按 route.meta.keepAlive !== false 分支缓存；清单里 keepAlive: false 才会不缓存。
排序：插件分组序 = 组内最小 order；manifest.order 参与排序，勿改回目录名排序。
主题外观联动：applyTheme 会同步 NSWindow.appearance / NSWindow.backgroundColor。强制 darkAqua / aqua 会把 webview 的 prefers-color-scheme 钉死；「跟随系统」必须传 dark: null 清除覆盖（见 set_window_appearance 三态设计）。

安全边界

工具页布局

ToolShell 只提供页头 + 全幅容器；居中列 / 分栏在页面内用原生 Tailwind 栅格（grid grid-cols-12 + col-start-* / col-span-*），禁止 mx-auto max-w-* 居中容器。
居中列必须偶数跨距（12 − 跨距为偶数）。
每个功能模块必须用 @/components/tool/Panel 包裹，禁止裸露模块、禁止在 Panel 内叠卡片。
bg-console 必须配 text-console-foreground*。
新 registry 组件若用裸 data-checked: / data-open: 等布尔变体，需转成 data-[state=...]:（reka-ui 2.10 只输出后者）；TabsList 横向高度被 group 变体钉死，需内联样式覆盖。

窗口材质

启用窗口材质后 set_window_background 不做实色打底（否则盖住材质），防白闪靠前端不透明底 保证；勿删 src-tauri/src/lib.rs 里 VIBRANCY_ACTIVE 的提前返回。

预览夹具

插件夹具只放 plugins/<id>/frontend/preview.ts（默认导出 Record<命令名, 返回值>，dev 下由预览桥 glob 并入），不要写进 src/dev/preview-bridge.ts（base 不接受 fork 插件名）。预览桥对未知业务命令返回 null（非数组），列表命令用 ?? [] 容错，否则浏览器预览白屏。

macOS dev 端口占用

tauri CLI（≤2.11.4）退出时靠 $TMPDIR/tauri-stop-dev-processes.sh 清理 dev server 进程树，但实测该脚本可能被创建为 0 字节 + 0o644（内容与权限写入双双静默失败）， !exists() 守卫又永不重建 → vite 成为孤儿 → 下次 tauri dev 报端口占用。

仅 chmod 不够（空脚本 = no-op），须写入原版内容 + 执行位（一次即可）：

cat > "${TMPDIR}tauri-stop-dev-processes.sh" << 'EOF'
#!/usr/bin/env sh
getcpid() {
    cpids=$(pgrep -P $1|xargs)
    for cpid in $cpids; do
        echo "$cpid"
        getcpid $cpid
    done
}
kill $(getcpid $1)
EOF
chmod 755 "${TMPDIR}tauri-stop-dev-processes.sh"

紧急兜底：lsof -ti:1420 | xargs -r kill -9。

其他高频问题

关窗后应用还在运行？ 设计行为：默认隐藏到托盘（后台常驻）。真正退出：托盘图标右键 → 退出（macOS 也可 Cmd+Q），可在设置页关闭「隐藏到托盘」。
Windows dev 报 ELIFECYCLE / 大数字退出码：退出时 tauri CLI 强制终止 vite dev server， Windows 报告 NTSTATUS 码（如 4294967295）。这是 dev 噪音，打包版不存在。
调整字号 / 主题后某些界面没变：多半硬编码了 px，改用 rem / 语义 token。

本地层编译依赖（ocr-rs 等）

这类重依赖属 fork 本地层，相关编译问题（macOS CXXFLAGS、Windows libclang）由 fork 自行处理并记录在 docs/local.md；base 不含这些依赖，无此问题。