DB Browser for SQLite 配置参数详解

目标：讲清 DB Browser for SQLite（DB4S）配置体系的完整面貌——配置文件位置与格式、四种查看/修改方式（GUI 偏好设置、配置文件直编、-o/-O 命令行开关、-S 独立设置文件与环境变量）、全部配置组与核心键的默认值，以及一份经实测写入验证的推荐配置模板。本文默认值口径取自 v3.13.1 源码 src/Settings.cpp，配置写入与生效行为在 Ubuntu 22.04 上对 3.12.1（apt 版）与 3.13.1（AppImage 版）实测验证。

一、环境信息

项目	值
操作系统	Ubuntu 22.04 LTS (jammy)，x86_64
实测版本	3.12.1-2（apt）、3.13.1（官方 AppImage，内置 SQLCipher 4.6.1）
配置文件路径	~/.config/sqlitebrowser/sqlitebrowser.conf
配置格式	QSettings INI 格式（分组节 `[组名]` + `键=值`）
设置机构名	sqlitebrowser（源码 `Application.cpp` 中 `setOrganizationName("sqlitebrowser")`）
源码依据	github.com/sqlitebrowser/sqlitebrowser v3.13.1 `src/Settings.cpp`（670 行）

💡 说明：DB4S 的配置体系由 Qt 的 QSettings 机制承载。Linux 上落盘为 ~/.config/sqlitebrowser/sqlitebrowser.conf；Windows 上为注册表，macOS 上为 plist——本文以 Linux INI 文件为主线。

二、前置条件

已按《Ubuntu 22.04 安装 DB Browser for SQLite 指南》完成安装（任一通道均可，配置文件三通道通用）；
命令行方式修改设置需要 sqlitebrowser 可执行文件在 PATH 中（apt 通道为 /usr/bin/sqlitebrowser，AppImage 通道用解包路径或全路径）；
无显示环境执行命令行时带 QT_QPA_PLATFORM=offscreen（3.13.1 AppImage 仅含 xcb 插件，需改用 Xvfb，见安装指南 5.3 节）。

三、参数查看与修改方式

3.1 GUI 偏好设置（最常用）

桌面会话内通过菜单 Edit → Preferences 打开偏好设置窗口，各分组标签页（General/Data Browser/SQL/SQL Log/Extensions/Remote 等）与下文配置组一一对应，保存后由应用写回配置文件。颜色、字体等复杂类型建议全部走 GUI 修改，避免手写序列化格式出错。

3.2 配置文件直接编辑

应用未运行时，可直接编辑 ~/.config/sqlitebrowser/sqlitebrowser.conf：

cat ~/.config/sqlitebrowser/sqlitebrowser.conf

首次运行后实测回显（26 字节的最小配置）：

[%General]
language=en_US

⚠️ 注意：请务必在应用退出后编辑——应用运行中手改配置，退出时会被应用内存中的设置反向覆盖。

3.3 命令行开关 `-o`（会话级）与 `-O`（持久化）

这是 DB4S 官方 Wiki 明确文档化的设置开关，格式为 组/键=值：

-o 组/键=值：仅当前会话生效，不写盘；
-O 组/键=值：写盘持久化（对启动的这一次会话也生效）。

实测一：用 -O 写入三个键（语言持久化为 zh_CN、最近文件数 10）：

QT_QPA_PLATFORM=offscreen sqlitebrowser -q -O General/language=zh_CN -O General/maxRecentFiles=10
cat ~/.config/sqlitebrowser/sqlitebrowser.conf

实测回显：

[%General]
language=zh_CN
maxRecentFiles=10

实测二：验证 -o 的临时性——先 -O db/prefetchsize=100000 落盘，再用 -o db/prefetchsize=1 启动，检查文件：

QT_QPA_PLATFORM=offscreen sqlitebrowser -q -o db/prefetchsize=1 -q
grep prefetch ~/.config/sqlitebrowser/sqlitebrowser.conf

实测回显：

prefetchsize=100000

值未被覆盖，证明 -o 只影响当次会话。

💡 补充：列表型键（键名以 list 结尾，如 recentFileList、extensions/list）的值用英文逗号分隔多个元素（源码 Application.cpp：endsWith("list") 时按逗号 split）。

3.4 `-S` 独立设置文件与 `DB4S_SETTINGS_FILE` 环境变量（3.13 起新增）

-S/--settings <文件> 让应用基于指定设置文件运行，与默认配置完全隔离，适合多套偏好并存（如"演示配置/生产配置"）。该参数为 3.13 起新增（3.12.1 的 --help 中没有它）：

echo "[%General]" > /root/my-zh.conf
echo "language=zh_CN" >> /root/my-zh.conf
/opt/db4s/squashfs-root/usr/bin/sqlitebrowser -S /root/my-zh.conf --version

实测回显（默认配置为 en_US 的前提下，-S 文件把语言切成了中文）：

DB Browser for SQLite 版本 3.13.1
构建时的最新提交: dce95c4

同样的能力也可以用环境变量实现：

DB4S_SETTINGS_FILE=/root/my-zh.conf /opt/db4s/squashfs-root/usr/bin/sqlitebrowser --version

实测回显同为中文版本信息。两者同时给出时，命令行参数优先，实测输出明确提示：

The user settings file location is replaced with the argument value instead of the environment variable value.
Ignored environment variable (DB4S_SETTINGS_FILE) value: /root/env.conf

⚠️ 注意（实测边界）：-S 文件要求首行必须是 [%General]（源码 isVaildSettingsFile 校验），否则告警 The given settings file is not a normal settings file. Please check again. 并回退到默认配置。另外，配合 -q 使用 -O 写 -S 指定的文件时，实测发现值不会落盘（-q 模式下应用提前退出、无事件循环；不带 -q 正常启动后再退出则写入正常）——需要向指定文件写值时，请不要用 -q。

四、参数总览

v3.13.1 Settings.cpp 中 getDefaultValue() 定义的配置组全集（组名 → 用途 → 键数）：

配置组	用途	代表键
`General`	全局行为：语言、界面风格、工具栏、最近文件、字体	language, appStyle, toolbarStyle*, maxRecentFiles, fontsize
`db`	数据库打开/连接默认值：编码、位置、外键、预取行数	defaultencoding, foreignkeys, prefetchsize, defaultlocation
`databrowser`	浏览数据标签页：字体、NULL/BLOB 显示、过滤、行数上限	null_text, blob_text, rows_limit, filter_delay
`editor`	SQL 编辑器：字体、缩进、换行、自动补全、标识符引号	font, tabsize, wrap_lines, auto_completion
`syntaxhighlighter`	语法高亮颜色/粗斜体（按关键字/表/函数等 token）	keyword_bold, keyword_colour, ...
`exportcsv`	CSV 导出：分隔符、引号、表头、换行符	separator, quotecharacter, firstrowheader
`importcsv`	CSV 导入：同上 + 字段裁剪、分表、本地格式	encoding, trimfields, separatetables
`exportsql`	SQL dump 导出选项：INSERT 列名、多行 INSERT	insertcolnames, insertmultiple
`exportjson`	JSON 导出：pretty print	prettyprint
`extensions` / `extension`	扩展加载：扩展列表、加载开关、正则扩展	list, enable_load_extension, disableregex
`MainWindow`	主窗口几何/布局/打开的标签页	geometry, windowState, openTabs
`SQLLogDock`	SQL 日志面板状态	Log
`PlotDock`	绘图面板：线型/点型	lineType, pointShape
`SchemaDock`	数据库结构页拖拽行为	dropSelectQuery, dropQualifiedNames
`checkversion`	新版本检查：开关与忽略阈值	enabled, ignmajor, ignminor, ignpatch
`remote`	File → Remote 远程克隆菜单	active, clonedirectory
`proxy`	网络代理：type 默认 system	type
`tmp`	运行态内部键（不落盘，如 fileWillBeOpenedFromCLI）	—

关键解读：MainWindow/SQLLogDock/PlotDock 等界面状态组由应用自动维护，手工修改意义不大；真正值得配置的是 General、db、databrowser、editor、extensions 五组。

五、核心参数分类详解

以下默认值均取自 v3.13.1 src/Settings.cpp::getDefaultValue()，标注"实测"的行为在 Ubuntu 22.04 上验证过。

5.1 General 组——全局行为

键	默认值	说明
language	QLocale::system().name()（如 en_US/zh_CN）	界面语言。实测：`-O General/language=zh_CN` 后 GUI 与命令行输出全部变中文
maxRecentFiles	5	最近文件列表长度。实测：`-O General/maxRecentFiles=10` 落盘生效
recentFileList	（空列表）	最近打开文件，逗号分隔（实测可见 `recentFileList=/root/test.db` 形态）
appStyle	0（FollowDesktopStyle）	应用风格：跟随桌面/浅色/深色
toolbarStyle	Qt::ToolButtonTextBesideIcon	主工具栏按钮样式（图标+文字）
toolbarStyleStructure / Browse / Sql / EditCell	结构页/浏览页/SQL 页/编辑单元格工具栏样式	结构页与主工具栏默认"图标旁文字"，浏览/SQL/编辑单元格默认"仅图标"
fontsize	应用默认字号	界面全局字号
DBFileExtensions	SQLite database files (.db .sqlite .sqlite3 .db3)	文件对话框的扩展名过滤器
promptsqltabsinnewproject	true	新建项目时是否提示打开 SQL 标签页

5.2 db 组——数据库连接默认值

键	默认值	说明
defaultencoding	"UTF-8"	新建数据库默认编码
defaultlocation	用户主目录	新建/打开对话框的初始目录
savedefaultlocation	2	是否记住上次目录（枚举）
lastlocation	继承 defaultlocation	上次访问目录
hideschemalinebreaks	true	结构视图是否折叠 schema 中的换行
foreignkeys	true	连接时是否默认执行 `PRAGMA foreign_keys=ON`
prefetchsize	50000（行）	浏览视图预取行数，大表浏览性能的关键参数。实测：`-O db/prefetchsize=100000` 落盘生效
defaultsqltext	（空）	新建 SQL 标签页的默认内容
fontsize	10	数据网格字号

5.3 databrowser 组——浏览数据标签页

键	默认值	说明
font / fontsize	Monospace / 10	数据网格等宽字体与字号
symbol_limit	5000	单元格内容超过该字符数后截断显示
rows_limit	10000000	浏览视图最大加载行数
complete_threshold	1000	编辑单元格自动补全阈值
image_preview	false	是否预览 BLOB 图片
auto_switch_mode	true	编辑单元格时自动切换显示模式
editor_word_wrap	true	单元格编辑器自动换行
null_text / blob_text	"NULL" / "BLOB"	NULL 与 BLOB 单元格的占位显示文本。实测：`-O databrowser/null_text=NULL` 落盘生效
filter_escape	"\"	过滤器转义符
filter_delay	200（毫秒）	过滤输入防抖时长。实测：`-O databrowser/filter_delay=200` 落盘生效
null_fg_colour / null_bg_colour / reg_* / formatted_* / bin_*	按桌面主题取色	各类单元格前景/背景色（Qt 序列化格式，建议 GUI 修改）

5.4 editor 组——SQL 编辑器

键	默认值	说明
font	Monospace	编辑器字体
fontsize	9（非 macOS）	编辑器字号
tabsize	4	缩进宽度。实测：`-O editor/tabsize=4` 落盘生效
indentation_use_tabs	true	缩进用 Tab 还是空格
wrap_lines	0（QsciScintilla::WrapNone）	长行换行策略（0=不换行）
identifier_quotes	0（DoubleQuotes）	自动补全/生成 SQL 时标识符引号风格
auto_completion	true	自动补全开关
upper_keywords	true	关键字自动大写。实测：`-O editor/upper_keywords=true` 落盘生效
error_indicators	true	错误行标红提示
horizontal_tiling	false	多 SQL 编辑器纵向/横向平铺
close_button_on_tabs	true	标签页关闭按钮
splitter1_sizes / splitter2_sizes	（空）	编辑器分割条位置（应用自动维护）

5.5 syntaxhighlighter 组——语法高亮

按 token 类型组合键，命名模式为 <token>_<属性>：

token：keyword、function、table、column、comment、string、glob、parameter、pragma、regex、blob 等；
属性：bold / italic / underline / colour；
默认：仅 keyword、table、function 三类加粗，其余不加粗不斜体不下划线；颜色按桌面主题取默认值（getDefaultColorValue）。

⚠️ 注意：颜色键落盘后是 @Variant(\0\0\0\x43...) 这类 Qt 二进制序列化串（官方 Wiki 的示例配置中也展示了该形态），手写易错，改色请走 GUI。

5.6 导入导出四组（exportcsv / importcsv / exportsql / exportjson）

组.键	默认值	说明
exportcsv.separator	`,`	导出分隔符
exportcsv.quotecharacter	`"`	引号字符
exportcsv.firstrowheader	true	首行是否作为表头
exportcsv.newlinecharacters	"\n"（Linux）	换行符（Windows 为 "\r\n"）
importcsv.firstrowheader	false	导入时首行是否为表头
importcsv.trimfields	true	导入时裁剪字段空白
importcsv.separatetables	false	多文件导入是否分表
importcsv.separator / quotecharacter / encoding	`,` / `"` / "UTF-8"	同导出语义
importcsv.localconventions	false	是否按本地数字/日期格式解析
exportsql.insertcolnames / insertmultiple / keeporiginal	false	SQL 导出：INSERT 带列名 / 每行一条 INSERT / 保留原始语句
exportsql.oldschema	0	旧 schema 版本兼容选项
exportjson.prettyprint	true	JSON 导出美化

5.7 extensions / extension 组——扩展加载

组.键	默认值	说明
extensions.list	（空列表）	启动时加载的扩展 .so 路径列表（逗号分隔）
extension.enable_load_extension	false	是否启用加载扩展能力（安全相关，默认关）
extension.disableregex	false	是否禁用内置 REGEXP 扩展

⚠️ 注意：加载第三方扩展等价于在数据库连接里执行任意 C 代码，enable_load_extension 保持默认 false 是合理的安全默认值，按需临时开启。

5.8 界面状态组（MainWindow / SQLLogDock / PlotDock / SchemaDock）

MainWindow.geometry/windowState/openTabs：窗口几何、停靠布局、上次打开的标签页——关闭窗口时自动写入，属于应用自维护状态；
SQLLogDock.Log：默认 "Application"，日志面板显示范围（Application/User SQL 等）；
PlotDock.lineType/pointShape：绘图面板默认线型（1=折线）与点型（4=圆点）；
SchemaDock.dropSelectQuery/dropQualifiedNames/dropEnquotedNames：结构页拖拽默认生成 SELECT、是否带限定名/引号（true/false/true）。

5.9 checkversion / remote / proxy / tmp 组

组.键	默认值	说明
checkversion.enabled	true	启动时检查新版本
checkversion.ignmajor / ignminor / ignpatch	999 / 0 / 0	忽略新版本的阈值（999 major 相当于"不忽略任何 major 提醒"）
remote.active	true	是否启用 File → Remote 菜单（基于 git 的远程克隆协作）
remote.clonedirectory	QStandardPaths AppDataLocation	远程克隆的存放目录
proxy.type	"system"	代理模式（system/none/http 等）
tmp.*	—	纯运行态键（如 fileWillBeOpenedFromCLI），`Settings::setValue` 以不落盘标志写入，配置文件中不会出现

六、推荐配置模板（实测生成）

以下模板不靠手写，而是用一组 -O 命令让 DB4S 自己生成（保证格式合法）：

QT_QPA_PLATFORM=offscreen sqlitebrowser -q \
  -O db/foreignkeys=true -O db/defaultencoding=UTF-8 \
  -O editor/tabsize=4 -O editor/upper_keywords=true \
  -O extensions/enable_load_extension=false \
  -O checkversion/enabled=true \
  -O databrowser/blob_text=BLOB -O databrowser/filter_delay=200 \
  -q
cat ~/.config/sqlitebrowser/sqlitebrowser.conf

实测回显（本机此前还有 maxRecentFiles/prefetchsize 等写入，一并保留原样）：

[%General]
language=en_US
maxRecentFiles=10
recentFileList=[ro]/root/test.db

[checkversion]
enabled=true

[databrowser]
blob_text=BLOB
filter_delay=200
null_text=NULL

[db]
defaultencoding=UTF-8
foreignkeys=true
prefetchsize=100000

[editor]
tabsize=4
upper_keywords=true

[extensions]
enable_load_extension=false

逐项说明与适用场景（开发/分析工作站，8GB 内存级别即可，无特殊磁盘要求）：

maxRecentFiles=10：提高最近文件数，多库切换场景减少重复查找；
recentFileList：应用自动维护的最近文件，无需手写（[ro] 前缀表示该文件曾以只读方式打开）；
db.prefetchsize=100000：浏览大表时一次取更多行，减少分页等待；小内存机器请保持默认 50000；
db.foreignkeys=true：与默认一致，显式写出以防其他机器漂移；
databrowser.filter_delay=200：过滤防抖，与默认一致，可按手感调 100–500；
editor.tabsize=4 + upper_keywords=true：与 SQL 编码规范一致；
extensions.enable_load_extension=false：安全默认，仅临时需要时通过 GUI/命令行开启；
checkversion.enabled=true：内网隔离环境可改为 false 关闭联网检查。

七、常见问题（FAQ）

7.1 改了配置文件，启动后又被改回去/没生效

应用退出时会用内存中的设置覆盖写盘。正确姿势：先退出应用，再改文件；或改用 -O 开关让应用自己写。

7.2 `-O` 配合 `-S` 与 `-q` 时设置没有写进指定文件

实测边界（见 3.4）：-q 让应用跳过主窗口与事件循环提前退出，QSettings 未及同步。不带 -q 正常启动再退出即可落盘；向默认配置写值时 -q -O 组合实测可正常落盘。

7.3 `-S` 文件被拒绝："not a normal settings file"

源码校验要求设置文件首行必须是 [%General]。新建文件时先写该行再追加键值即可。

7.4 环境变量与 `-S` 同时存在用哪个

命令行参数优先。实测回显告警：The user settings file location is replaced with the argument value instead of the environment variable value.（3.4 节原文）。

7.5 颜色类键值是乱码（@Variant(\0\0\0...)）

这是 Qt 的二进制序列化格式，属正常现象。修改颜色请走 GUI 偏好设置，或删除对应键让应用恢复默认。

7.6 如何整体恢复默认

删除配置目录后重启应用即可回到出厂状态（含语言回退为系统 locale）：

rm -rf ~/.config/sqlitebrowser

7.7 配置里的 language 与系统语言

默认值为 QLocale::system().name()——系统为中文桌面时默认就是 zh_CN，无需手工设置；翻译缺失的条目会回落英文。

八、参考链接

官方 Wiki 命令行文档（-o/-O 语义与示例设置文件）：https://github.com/sqlitebrowser/sqlitebrowser/wiki/Command-Line-Interface
设置默认值源码（v3.13.1）：https://github.com/sqlitebrowser/sqlitebrowser/blob/v3.13.1/src/Settings.cpp
应用启动与参数解析源码：https://github.com/sqlitebrowser/sqlitebrowser/blob/v3.13.1/src/Application.cpp
本专栏姊妹篇：《Ubuntu 22.04 安装 DB Browser for SQLite 指南》、《DB Browser for SQLite 介绍与选型指南》、《DB Browser for SQLite 常用操作与自动化边界详解》

DB Browser for SQLite 配置参数详解

DB Browser for SQLite 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 GUI 偏好设置（最常用）

3.2 配置文件直接编辑

3.3 命令行开关 -o（会话级）与 -O（持久化）

3.4 -S 独立设置文件与 DB4S_SETTINGS_FILE 环境变量（3.13 起新增）

四、参数总览

五、核心参数分类详解

5.1 General 组——全局行为

5.2 db 组——数据库连接默认值

5.3 databrowser 组——浏览数据标签页

5.4 editor 组——SQL 编辑器

5.5 syntaxhighlighter 组——语法高亮

5.6 导入导出四组（exportcsv / importcsv / exportsql / exportjson）

5.7 extensions / extension 组——扩展加载

5.8 界面状态组（MainWindow / SQLLogDock / PlotDock / SchemaDock）

5.9 checkversion / remote / proxy / tmp 组

六、推荐配置模板（实测生成）

七、常见问题（FAQ）

7.1 改了配置文件，启动后又被改回去/没生效

7.2 -O 配合 -S 与 -q 时设置没有写进指定文件

7.3 -S 文件被拒绝："not a normal settings file"

7.4 环境变量与 -S 同时存在用哪个

7.5 颜色类键值是乱码（@Variant(\0\0\0...)）

7.6 如何整体恢复默认

7.7 配置里的 language 与系统语言

八、参考链接

3.3 命令行开关 `-o`（会话级）与 `-O`（持久化）

3.4 `-S` 独立设置文件与 `DB4S_SETTINGS_FILE` 环境变量（3.13 起新增）

7.2 `-O` 配合 `-S` 与 `-q` 时设置没有写进指定文件

7.3 `-S` 文件被拒绝："not a normal settings file"

7.4 环境变量与 `-S` 同时存在用哪个