常见问题排查
找到症状，看原因，照着修。如果这里没有你遇到的情况，请提交 issue，写明你做了什么、看到了什么。
安装与启动
| 症状 | 原因与解决 |
|---|---|
| 在 Intel Mac 上打不开 | 发布版只为 Apple silicon 构建。在 Intel 上请从源码构建 |
ducklocal: command not found | 磁盘映像只安装应用，不安装命令。请把可执行文件链接到 PATH |
| 窗口开着时终端被占用 | 从终端打开 GUI 会在前台运行。改从“应用程序”启动，或者把那个终端留给它 |
| 历史、设置或已登记的文件不再保存 | 另一个 DuckLocal 正在运行，占用了应用数据文件。退出另一个后重新启动 |
打开数据
| 症状 | 原因与解决 |
|---|---|
指定的路径报 文件不存在 | 路径不存在，或者相对于的不是你以为的目录。用绝对路径最稳妥 |
| 文件夹报告没有数据文件 | 里面没有匹配 .csv、.tsv、.txt、.parquet、.json、.ndjson、.jsonl、.xlsx、.xls、.xlsb 或 .ods 的文件 |
| 文件夹导入的文件比预期少 | 隐藏条目和符号链接会被跳过，一次打开最多挂载 256 个文件。请分子文件夹打开 |
| 某个路径意外地被当作数据库打开 | 任何已存在、但不是数据文件的文件都会被当作 DuckDB 数据库。打不开时，DuckLocal 会回退到内存模式并显示错误 |
| 未挂载 …：当前数据库已有名为 … 的表或视图 | 当前数据库里有一个与已登记文件同名的表或视图。DuckLocal 不会替换它。把其中一个改名或删除，或者从 本地文件 移除该文件后重新打开，让它拿到新名字 |
| 无法恢复相对路径 … | 这个文件是按相对路径登记的，新会话里无法解析。从 本地文件 移除后重新打开 |
视图名是 sales_2 而不是 sales | 已有同名的文件或表，新的那个就加了后缀 |
| 文件对应的视图不是最新的 | 视图每次查询都会读取文件。如果 CSV 的列结构变了，点侧边栏的 刷新 Schema |
运行查询
| 症状 | 原因与解决 |
|---|---|
| 运行 没反应 | 已有查询在运行。没有取消，也没有超时；想放弃一条查询只能退出重开 |
| ⌘↵ 显示了编辑器而不是运行 | 在首次运行界面上，⌘↵ 的意思是“给我一个编辑器”。再按一次就会运行 |
| 结果提前截断并有提示 | 达到了 100,000 行或 2,000,000 个单元格的上限。请缩小查询范围；没有分页 |
| 时间戳看起来偏了 | 表格按 UTC 显示时间戳，而不是本地时间 |
| 点击表头不排序 | 没有客户端排序。请用 ORDER BY |
| 点了表或历史记录后我的 SQL 没了 | 这些点击会替换整个编辑器内容。临时的尝试请用新的查询 Tab |
| 导出时悄悄覆盖了文件 | 导出会直接写入你给的路径，不会询问。请换个文件名 |
S3
| 症状 | 原因与解决 |
|---|---|
| S3 凭据丢了 | 凭据按设计只在本次会话有效，打开或切换数据库也会清除。请重新配置 |
| 离线时配置 S3 失败 | 首次使用会执行 INSTALL httpfs，需要下载扩展。联网一次后就会缓存 |
| 临时（STS）凭据被拒绝 | 不会发送 session token。请使用长期密钥——见 S3 与 httpfs |
| bucket 看起来比实际少 | 每一层最多列出 1,000 个条目。改用通配符查询，比如 's3://bucket/prefix/*.parquet' |
应用与 Dashboard
| 症状 | 原因与解决 |
|---|---|
| 应用标签页问 要运行这个应用吗？ | 一个文件夹第一次作为应用打开时，DuckLocal 会在运行其代码前询问，因为应用的 SQL 能读写 SQL 编辑器能碰到的一切。不是你写的就先点 先看源码；信任并运行 会按文件夹记住 |
| dashboard 的图表提示查询必须只读 | .dash 里的查询试图写入（DDL、DML、COPY、ATTACH 等）。Dashboard 只执行只读语句；准备工作请放到 SQL 编辑器里做 |
dashboard 里的 PIVOT 被拒绝 | 不写明 IN (…) 列表时，DuckDB 会把 PIVOT 拆成多条语句。请列出取值：PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue) |
外观
| 症状 | 原因与解决 |
|---|---|
| 每次启动主题都回到浅色 | 主题不会被保存；语言会 |
| 文字或图标太小 / 太大 | 用标题栏的 Aa 按钮，或 ⌘+ / ⌘− / ⌘0。见界面大小 |
| 界面语言不对 | 用标题栏的 EN / 中 按钮切换，选择会被记住 |
从头开始
要清除历史、已登记的文件、记住的标签页和设置，先退出 DuckLocal，再删除它的应用数据目录：
bash
rm -rf ~/Library/Application\ Support/DuckLocal你的数据文件不会受任何影响——只会删除 DuckLocal 自己的记录。里面具体存了什么，见设置与应用数据。