常见问题排查
先确认具体现象，排查对应原因，并按步骤修复。如果文中未列出你遇到的问题，请提交 issue，并说明具体操作步骤与实际表现。
安装与启动
| 症状 | 原因与解决 |
|---|---|
| 在 Intel Mac 上打不开 | macOS 发布版只为 Apple silicon 构建。在 Intel 上请从源码构建 |
| 文档里的快捷键在 Windows 或 Linux 上没反应 | 把 ⌘ 换成 Ctrl：⌘↵ 在那里是 Ctrl+Enter |
ducklocal: command not found | 磁盘映像只安装应用，不安装命令。把可执行文件链接到 PATH即可 |
| 窗口开着时终端被占用 | 从终端打开 GUI 会在前台运行。改从“应用程序”启动，或者就把那个终端留给它 |
| 历史、设置或已登记的文件不再保存 | 另一个 DuckLocal 正在运行，占用了应用数据文件。退出另一个后重新启动 |
| DuckLocal 上次意外退出 | 它崩溃了，并在日志文件夹里留了一份报告。点 显示报告，附在 issue 里，见存储位置 |
| 检查更新失败 | 鼠标悬停看原因：没联网、代理拦截，或下载的文件和校验值不符。点击重试，或者去 GitHub 下载，见检查更新 |
打开数据
| 症状 | 原因与解决 |
|---|---|
指定的路径报 文件不存在 | 路径不存在，或者相对路径的起点和你以为的不一样。用绝对路径最稳妥 |
| 文件夹报告没有数据文件 | 里面没有匹配 .csv、.tsv、.txt、.parquet、.json、.ndjson、.jsonl、.xlsx、.xls、.xlsb 或 .ods 的文件 |
| 文件夹导入的文件比预期少 | 隐藏条目和符号链接会跳过，一次最多挂载 256 个文件。把子文件夹分开来打开 |
| 某个路径意外地作为数据库打开了 | 只要文件存在但不是数据文件，就会当作 DuckDB 数据库打开。打不开时，DuckLocal 会说明原因；如果是在启动时，会退回内存模式。见打开数据库 |
| 未挂载 …：当前数据库已有名为 … 的表或视图 | 当前数据库里有一个与已登记文件同名的表或视图。DuckLocal 不会替换它。把其中一个改名或删除，或者从 本地文件 移除该文件后重新打开，让它拿到新名字 |
| 无法恢复相对路径 … | 这个文件是按相对路径登记的，新会话里无法解析。从 本地文件 移除后重新打开 |
视图名是 sales_2 而不是 sales | 已有同名的文件或表，新的那个就加了后缀 |
| 文件对应的视图不是最新的 | 视图每次查询都会读取文件。如果 CSV 的列结构变了，点侧栏的 刷新 Schema |
打开数据库
| 症状 | 原因与解决 |
|---|---|
| 提示说数据库由更新版本的 DuckDB 创建 | 文件的存储格式比 DuckLocal 内置的 DuckDB 能读的更新。在创建该文件的那个 DuckDB 里运行提示中给出的 ATTACH … COPY FROM DATABASE 几行，再打开复制出来的文件。见数据库文件打不开时 |
| 提示说数据库来自 DuckDB v0.9 或更早版本 | 用原来的 DuckDB 执行 EXPORT DATABASE 'dir'，再在 DuckLocal 里执行 IMPORT DATABASE 'dir' |
| 提示说这是 SQLite 数据库 | 不要直接打开，改用 打开 → 附加数据库… 把它附加进来 |
| 提示说这个文件不是 DuckDB 数据库文件 | 它的扩展名不在 DuckLocal 认作数据文件的范围内，于是被当作数据库尝试打开。把扩展名改成支持的格式，或者在 SQL 里读取，例如 SELECT * FROM read_csv('export.dat') |
| DuckDB 报告无法给文件加锁（could not set lock） | 另一个程序——另一个 DuckDB、某个脚本、另一个应用——正以可写方式打开这个数据库，而 DuckDB 只允许一个进程写同一个文件。在那边关掉它，再重新打开 |
| DuckDB 报告权限不足（permission denied） | 你的账户读不了这个文件，或者写不了它：主数据库是以可写方式打开的。修改文件权限，或者勾选 只读 把它附加进来 |
| 打开数据库失败，什么都没变 | DuckLocal 运行期间这是正常的：打开失败时保留原来的工作区。看通知里的原因 |
| 状态栏提示 DuckDB v1.x+ 可读，同事却打不开这个文件 | 对方的 DuckDB 比这个版本旧。对方需要升级，或者由你用较旧的 STORAGE_VERSION 复制一份，见哪些 DuckDB 能读这个数据库 |
附加数据库
| 症状 | 原因与解决 |
|---|---|
| 重新启动后，附加的数据库不见了 | 启动时它的文件不在记录的路径上，所以被跳过。登记仍然保留；把文件放回去，下次建立连接时它就会回来 |
| 这个数据库已经打开了，名为 …。 | 这个文件已经是主数据库，或者已经以这个名字附加。直接用这个名字查询即可 |
| 无法附加 …：名称 … 已被当前数据库占用。 | 连接里已经有别的东西用了记录的别名——比如你在 SQL 里用同样的名字附加过一个数据库。先 DETACH 那一个，再重新打开数据库或重启应用 |
| 写入附加的数据库失败 | 它是以只读方式附加的（默认如此）。在侧栏选 分离数据库，再取消勾选 只读 重新附加 |
| 附加时新建了一个空数据库 | 取消勾选 只读 时，不存在的 DuckDB 路径会被新建。分离它，删掉这个空文件，再检查路径 |
| 不带库名的表名找到了别的表 | 不带库名的表名在默认数据库里查找。右键点击数据库选 设为默认数据库，或者写成 别名.表 |
访达与快速查看
以下内容只适用于 macOS。
| 症状 | 原因与解决 |
|---|---|
双击 .parquet 或 .duckdb 文件打开了别的应用 | 那个应用已经是默认应用。在访达里 显示简介 → 打开方式，选 DuckLocal，再点 全部更改… |
| 双击 CSV 或 Excel 文件没有用 DuckLocal 打开 | 有意如此：DuckLocal 不抢这些格式。用 打开方式 → DuckLocal，或者把文件拖到程序坞图标上 |
| 打开方式 里没有 DuckLocal，或按空格键看不到 DuckLocal 的预览 | macOS 还没登记这个应用。把它移到“应用程序”里并启动一次。预览的话，再在终端里运行 qlmanage -r，并在“系统设置”的扩展设置里确认快速查看下的 DuckLocal Preview 已开启 |
普通 .json 或 Excel 文件没有 DuckLocal 的预览 | 有意如此：这些交给 macOS 自带的预览。.jsonl 和 .ndjson 文件会有预览 |
| 预览只显示 50 行 | 有意如此：预览从不扫描整个文件。其余的数据请在 DuckLocal 里打开查看 |
.duckdb 文件的预览显示错误 | 预览用的是 DuckLocal 自带的 DuckDB，所以较新 DuckDB 写的文件在这里同样打不开。见打开数据库 |
运行查询
| 症状 | 原因与解决 |
|---|---|
| 运行 没反应 | 已有查询在运行。点运行旁边的 停止，或按 ⌘.，即可中断 |
查询失败，报 Interrupted | 运行期间有人点了 停止（或按了 ⌘.）。重新运行即可 |
| SQL 里有一段红色波浪线 | 上次运行在那里出错。看 查询失败 提示里的信息；下次运行时标记会清除 |
| ⌘↵ 显示了编辑器而不是运行 | 在首次运行界面上，⌘↵ 的意思是“给我一个编辑器”。再按一次就会运行 |
| 结果提前截断并有提示 | 达到了 100,000 行或 2,000,000 个单元格的上限。缩小查询范围即可，没有分页 |
| 时间戳看起来偏了 | 表格里的时间戳是 UTC，不是本地时间 |
TIMETZ 的时区偏移不见了，或者 BIT、BIGNUM 的值看起来是一串字节 | 这些类型在传给 DuckLocal 的途中无法和普通值区分。在 SQL 里写 CAST(column AS VARCHAR) 就能看到真实的值 |
| 排序没有带回预览之外的行 | 点表头只会重排已加载的行。要在截断之前对完整结果排序，请在 SQL 中使用 ORDER BY |
| 查询需要尚未安装的扩展 | 不再自动下载缺失的扩展。先在 扩展 标签页显式安装，再加载或重跑查询 |
| 0.3.0 之前能运行的查询，提示扩展未安装或函数不存在 | DuckLocal 0.3.0 用的是 DuckDB 2.0，装好的扩展按 DuckDB 版本分开存放。在 扩展 标签页里重新安装即可，见扩展 |
minutes 这样的裸列别名导致解析错误 | 它是 SQL 关键字。写成 AS minutes，或者给别名加双引号：SELECT count(*) AS "minutes" FROM events |
| 点了表或历史记录后我的 SQL 没了 | 这类点击会替换编辑器里的全部内容。临时试写的 SQL 最好放在新的查询标签页里 |
| 导出时悄悄覆盖了文件 | 导出会直接写入给定的路径，不作询问。换个文件名即可 |
S3
| 症状 | 原因与解决 |
|---|---|
| S3 凭据丢了 | 凭据本来就只在当前会话有效，打开或切换数据库也会清除。重新配置即可 |
| 离线时配置 S3 失败 | 首次使用会执行 INSTALL httpfs，要下载扩展。联网装过一次后就会缓存下来 |
| 临时（STS）凭据被拒绝 | 不会发送会话令牌（session token），请改用长期密钥，见 S3 与 httpfs |
| bucket 看起来比实际少 | 每一层最多列出 1,000 个条目。改用通配符查询，比如 's3://bucket/prefix/*.parquet' |
仪表盘（dashboard）
| 症状 | 原因与解决 |
|---|---|
| 仪表盘的图表提示查询必须只读 | .dash 里的查询试图写入（DDL、DML、COPY、ATTACH 等）。仪表盘只执行只读语句；准备工作请放到 SQL 编辑器里做 |
| agent 没看到我的评论 | 评论不会自动发给谁，要 agent 自己去读。让它运行 ducklocal comments 文件；装了官方 skill 的 agent，直接说“处理 文件 上的评论”即可 |
| agent 的回复或修改没有显示 | 窗口在一秒内就会跟上规格文件和 文件.comments.json 的变化。如果规格文件已经通不过校验，仪表盘会保留上一个能用的版本，并在上方说明原因；点 查看 spec 看文件内容 |
仪表盘里的 PIVOT 被拒绝 | 嵌在 SELECT 或 WITH 里的 PIVOT 必须写明取值。请列出取值：PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)，或者让查询以 PIVOT 开头 |
外观
| 症状 | 原因与解决 |
|---|---|
| 每次启动主题都回到浅色 | 主题不会在两次启动之间保存，语言会保存 |
| 文字或图标太小 / 太大 | 用标题栏的 Aa 按钮，或 ⌘+ / ⌘− / ⌘0。见界面大小 |
| 界面语言不对 | 用标题栏的 EN / 中 按钮切换，选择会记住 |
从头开始
要清除历史、已登记的文件、打开的标签页和设置，先退出 DuckLocal，再删除它的应用数据目录：
bash
rm -rf ~/Library/Application\ Support/DuckLocal数据文件本身不受影响，删掉的只是 DuckLocal 自己的记录。这个目录里具体存了什么，见设置与应用数据。