# 快速上手

> 在 Mac、Windows 或 Linux 上安装 DuckLocal、添加 ducklocal 命令、打开第一个 CSV、Parquet、JSON 或 Excel 文件，五分钟内跑通第一条 DuckDB SQL 查询。

Source: https://ducklocal.app/docs/zh/getting-started

**[English](../getting-started.md)**

DuckLocal 是一个桌面应用，让你直接用 SQL 查询本机上的数据文件。不用运行服务器，不用配置连接，也不用注册账号，选好文件就能开始查询。本页带你从下载走到第一条查询结果，大约五分钟。

## 1. 安装 {#install}

DuckLocal 支持 macOS、Windows 和 Linux。点击下方链接可从 `dl.ducklocal.app` 获取最新版本；安装文件与发布说明也可在 [GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest) 查看。

本文档已按 [v0.4.0 发布版本](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0)更新（2026 年 11 月 4 日）。这个版本新增了 [Agent 工作流](agent-workflows.md)：受限 SQL、可确认结果的窗口交接、仪表盘修改提议、分析记录和可移动的项目。仪表盘里的折线图和散点图改为按实际时间定位，gzip 压缩的 JSON 和 CSV 也能直接当数据打开。如果你是从 0.3.0 之前的版本更新，请重新安装扩展，因为 0.3.0 把 DuckLocal 升级到了 DuckDB 2.0。

### Mac

需要 **macOS 12 及以上、Apple silicon 芯片**（M1 或更新）。

1. 下载 [`ducklocal-macos-arm64.dmg`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg)。
2. 打开磁盘映像，把 **DuckLocal** 拖到“应用程序”上。
3. 从“应用程序”或聚焦搜索启动 DuckLocal。

磁盘映像已经过 Apple 签名和公证，打开时不需要任何绕过 Gatekeeper 的操作。

### Windows

需要 **64 位 Windows 10 及以上**。

1. 下载 [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/ducklocal-windows-x86_64.zip) 并解压。
2. 运行解压出的文件夹里的 `ducklocal.exe`。这个版本暂未进行代码签名，首次启动时可能出现 **Windows 已保护你的电脑**——点击 **更多信息**，再点击 **仍要运行**。

### Linux

需要 **x86_64** 系统、**glibc 2.35 或更新**（Ubuntu 22.04、Debian 12、Fedora 36 及以上），以及支持 Vulkan 的显卡驱动。

```bash
curl -LO https://dl.ducklocal.app/latest/ducklocal-linux-x86_64.tar.gz
tar -xzf ducklocal-linux-x86_64.tar.gz
./ducklocal-linux-x86_64/ducklocal
```

::: details 改为从源码构建
需要 Rust stable 1.85.1 或更新版本，以及 C++ 工具链（Xcode Command Line Tools）。DuckDB 由内置源码编译，首次构建需要几分钟，并占用几 GB 磁盘空间。

```bash
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocal
```

可执行文件是 `./target/release/ducklocal`，本指南中写 `ducklocal` 的地方都可以用它代替。打包 `.app` 的方法见[开发指南](development.md)。
:::

## 2. 添加 `ducklocal` 命令（可选） {#add-command}

应用里的功能都用不着终端。如果还想从命令行打开数据，或者让 AI 助手通过 [CLI](cli.md) 分析数据，在应用里添加命令即可：

1. 点击标题栏的机器人按钮，或在菜单栏选择 **DuckLocal → 命令行与 AI…**。
2. 点击 **安装命令**。在 Mac 上，系统会请你输入密码，以写入 `/usr/local/bin`。
3. 打开新的终端，确认一下：`ducklocal --version`。

这个命令是指向应用的链接，所以更新 DuckLocal 后，命令也随之更新。要更新，点状态栏最右边的版本号：新版本会下载好，重启时安装（见[检查更新](settings-and-data.md#update-check)）。Mac 上装在 `/usr/local/bin`，Linux 上装在 `~/.local/bin`；Windows 上会把应用所在文件夹加入 `Path`。

在同一个对话框里，**添加到 Claude Code** 会安装 DuckLocal 的 AI 智能体技能包（agent skill），让 Claude Code 知道怎样查询你的文件；**复制说明** 会复制一段简短说明，粘贴给任何其他 AI 助手即可。详见 [AI CLI 与官方技能包](cli.md#安装官方-skill)。

::: details 手动添加
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocal
```

删除命令：`sudo rm /usr/local/bin/ducklocal`。在 Linux 上，把解压出的可执行文件链接到 `~/.local/bin`；在 Windows 上，把解压出的文件夹加入 `Path`。
:::

## 3. 打开数据

首次启动时，会先出现一段由小鸭子带路的简短引导：接入 AI 助手、打开数据、侧边栏、运行查询、查看结果。任何一步都可以点 **跳过**。想再看一遍，Mac 上在 **DuckLocal** 菜单里选 **显示新手引导**，或者在状态栏右端版本号的右键菜单里选。

引导后面是标题为 **把数据拖进来** 的界面。以下任意一种方式都能导入数据：

- 把 CSV、TSV、Parquet、JSON、Excel 文件或整个文件夹**拖到窗口上**。
- 点击 **打开文件** 或 **打开文件夹**。
- 在 Mac 上，在访达里**双击** `.parquet` 或 `.duckdb` 文件；CSV、JSON 和 Excel 文件则在 **打开方式** 里选 DuckLocal。见[从访达打开](data-sources.md#open-from-finder)。
- 在终端里写出路径：

  ```bash
  ducklocal ./sales.csv         # 单个文件
  ducklocal ./logs/             # 递归打开文件夹下的所有数据文件
  ducklocal './data/*.parquet'  # 通配符——加引号，避免被 shell 提前展开
  ducklocal warehouse.duckdb    # 已有的 DuckDB 数据库
  ```

每个文件都会变成一个以文件名命名的视图（`sales.csv` 变成 `sales`），出现在侧栏的 **本地文件** 下，并列出各列和行数。DuckLocal 在原位置读取文件，不复制，也不上传。

打开过的文件会记下来，下次启动还是同一个工作区。格式、文件夹、通配符和数据库的细节见[数据源](data-sources.md)。

在 Mac 上，打开文件之前还可以先瞄一眼：在访达里选中它，按**空格键**。DuckLocal 的[快速查看预览](data-sources.md#quick-look)会显示 Parquet、DuckDB、CSV、TSV 和 JSON Lines 文件的列和前几行。

::: tip 手头没有数据？
[10 分钟上手教程](tutorial.md)会用一个小样例文件一步步带你走一遍。
:::

## 4. 运行查询

点击 **新建查询**（打开数据后，编辑器也会自动出现）。输入 SQL，按 **⌘↵**（Cmd+Enter；Windows 和 Linux 上是 Ctrl+Enter）：

```sql
SELECT * FROM sales LIMIT 20;
```

把 `sales` 换成你侧栏里的任意视图名。

结果出现在编辑器下方的面板里。切换到 **图表** 可以快速看个大概，也可以导出为 CSV 或 Parquet。编辑器上方的工具栏有 **运行**、**格式化** 和 **EXPLAIN**。

还有个捷径：在侧栏点表旁边的播放按钮，会生成现成的 `SELECT * … LIMIT 100`；点列名则只查询这一列。

## 接下来

- [10 分钟上手教程](tutorial.md) —— 用样例数据走一遍
- [数据源](data-sources.md) —— 格式、文件夹、通配符、数据库、访达与快速查看
- [SQL 编辑器](sql-editor.md) —— 标签页、快捷键、自动补全、EXPLAIN
- [结果与图表](results-and-charts.md) —— 过滤、导出、图表、列概览
- [仪表盘（.dash）](dashboards.md) —— 用文本文件写仪表盘，并和 AI agent 一起审阅
- [常见问题排查](troubleshooting.md) —— 遇到不对劲的地方时