BoltDB自2026年起必须用go.etcd.io/bbolt导入，旧路径已归档；打开数据库需设0600权限；事务须在Update/View内调用Bucket；务必defer db.Close()；建桶优先用CreateBucketIfNotExists；写操作单条用Update、批量用Batch；只读用View；调试用boltbrowser查看.db文件。
BoltDB 在 2026 年已正式由 github.com/boltdb/bolt 迁移至 go.etcd.io/bbolt，直接用旧 import 会编译失败 —— 这是绝大多数人踩的第一个坑。
怎么正确引入和打开数据库？
新项目必须用 go.etcd.io/bbolt，旧 import（如 github.com/boltdb/bolt）早已归档，Go 1.21+ 默认拒绝加载已弃用模块。即使你本地有缓存，go mod tidy 也会报错：module github.com/boltdb/bolt: not found。
- 安装命令是：
go get go.etcd.io/bbolt@latest - 打开数据库时，权限掩码
0600是安全底线 —— BoltDB 文件含原始数据，不设权限等于裸奔 - 别在
Update或View外调用tx.Bucket()，事务未开启时返回nil，后续Put/Get会 panic - 务必用
defer db.Close()：BoltDB 对文件加独占锁，进程不退出又没 Close，其他程序（包括你自己重启的实例）会卡死在Open上
为什么 CreateBucketIfNotExists 比 CreateBucket 更安全？
CreateBucket 在桶已存在时直接返回 error（bucket already exists），而大多数业务逻辑不需要“建桶失败就中止”，尤其在初始化阶段反复运行脚本时容易炸。
-
CreateBucketIfNotExists是幂等操作，推荐作为默认选择 - 它返回
*bbolt.Bucket和nilerror，可直接链式使用，比如：b := tx.Bucket([]byte("users")).Put(...) - 注意：桶名是
[]byte，不是 string；传"users"会编译失败，必须写成[]byte("users")或用[]byte("users")显式转换
读写事务选 Update 还是 Batch？
单条写用 Update，批量写（比如导入 100+ 条记录）必须用 Batch —— 否则性能断崖式下跌。
立即学习“go语言免费学习笔记（深入）”；
-
Update每次都新建事务、刷盘、释放锁，100 次Update≈ 100 次磁盘 I/O -
Batch会自动合并多个写请求到一个事务里，吞吐量提升 3–5 倍（实测数据见官方db_test.go的BenchmarkDBBatchAutomatic） -
Batch内部有超时控制（默认 1 秒），如果写入耗时过长，它会自动降级为多次Update，所以不用手动加重试 - 只读场景一律用
View：它不抢写锁，可并发执行，而Update是全局排他锁
调试时怎么直观查看 .db 文件内容？
BoltDB 是二进制 mmap 文件，不能直接用文本编辑器看。靠打印日志太低效，推荐用轻量 CLI 工具 boltbrowser：
- 安装：
go get github.com/br0xen/boltbrowser - 启动：
boltbrowser my.db，会开一个本地 Web 页面，树状展示所有 bucket 和 key/value - 注意：它只读打开，不会加锁，不影响你的程序运行；但别在生产环境随意暴露该端口
- 如果遇到
invalid page type错误，大概率是文件被截断或损坏 —— 此时db.View会 panic，需从备份恢复
最常被忽略的一点：BoltDB 不支持并发写事务，也不支持跨 goroutine 复用 *bbolt.Tx。所有事务对象必须在回调函数内使用，传出去就失效。
