NoneBot2 本地数据存储实战：nonebot-plugin-localstore 安装、配置与路径管理原理-育师

后端
即时通讯

【免费下载链接】nonebot2

跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python

项目地址：https://gitcode.com/gh_mirrors/no/nonebot2

持久化数据存储是聊天机器人插件开发中最常见的需求之一——用户的个人信息、群组设置、使用记录等都需要在机器人重启后依然保留。除了引入数据库等第三方存储外，NoneBot2 官方推荐的轻量方案是使用本地文件系统，通过nonebot-plugin-localstore插件自动获取符合操作系统规范的数据存储路径，让插件开发者无需关心平台差异即可安全地读写文件。本文以 NoneBot2 当前仓库（2.5.0 版本文档体系）为基准，完整讲解该插件的安装方式、六大路径获取 API、全部配置项及其跨平台默认值，并结合 NoneBot2 核心源码剖析其背后的require依赖加载、插件标识符与配置解析原理。读完本文，你将能够在自己的插件中正确、规范地接入本地文件存储。

为什么插件需要本地文件存储

在 NoneBot2 的插件化生态中，插件经常需要保存两类信息：

会话性临时数据：如图片缓存、接口响应缓存，丢失后可以重新获取；
持久化业务数据：如用户等级、群组白名单、自定义词库，必须跨重启保留。

直接在自己的插件代码里硬编码路径（例如./data/my_plugin/xxx.json）存在明显问题：不同操作系统对"缓存目录""数据目录""配置目录"有各自的规范位置，硬编码路径既不符合平台习惯，也容易在打包分发后因工作目录不同而失效。NoneBot2 官方提供了nonebot-plugin-localstore插件来解决这一问题——它封装了跨平台的目录定位逻辑，插件只需调用统一的方法即可拿到正确的pathlib.Path路径。

在 NoneBot2 官方商店数据中，该插件的模块名为nonebot_plugin_localstore，项目链接为nonebot-plugin-localstore，属于官方维护插件（见 assets/plugins.json5）。

安装插件

在使用前，需要先将nonebot-plugin-localstore安装到当前项目中。可以参照获取商店内容一节了解 NoneBot2 商店插件体系，安装方式有以下几种。

方式一：nb-cli 命令安装（推荐）

在项目目录下执行：

nb plugin install nonebot-plugin-localstore

nb-cli会自动安装插件并将其添加到加载列表中，是最省心的方式。也可以进入交互式安装：

$ nb plugin install [?] 想要安装的插件名称: nonebot-plugin-localstore

方式二：pip 安装

pip install nonebot-plugin-localstore

使用 pip 安装完成后，需要参照加载插件自行配置加载，插件加载方式与 NoneBot2 的插件加载机制相关（如load_plugin、load_all_plugins、load_from_toml等）。

安装完成后，nonebot-plugin-localstore还提供nb-cli脚本命令：

nb localstore

运行该命令可以检查当前环境下各数据存储路径的实际指向，方便在配置自定义目录前先确认默认路径是否符合预期。

使用插件：require 加载与六大路径 API

nonebot-plugin-localstore是一个"为其他插件提供功能支持"的服务型插件，因此使用前必须先通过 NoneBot2 的跨插件访问机制声明依赖。

为什么必须用 require 而不是直接 import

NoneBot2 插件系统通过 Python Import Hooks 实现插件加载与跟踪管理（详见跨插件访问）。在 NoneBot2 跟踪插件之前直接import外部插件，会导致该插件加载失败或不被识别。正确的做法是在 import 之前，先用require声明依赖——NoneBot2 会在加载当前插件时检查依赖插件是否已加载，若未加载会尝试优先加载。

从源码看，require的实际实现位于 nonebot/plugin/load.py：它接受"插件模块名或插件标识符"作为参数，通过get_plugin查找已加载插件；若未加载，则先从已声明的PluginManager中尝试加载，再退化为load_plugin直接加载；全部失败时抛出RuntimeError: Cannot load plugin "xxx"!。返回值为依赖插件的模块对象，之后就可以正常import使用其导出的功能。

from nonebot import require require("nonebot_plugin_localstore") import nonebot_plugin_localstore as store

require已由 NoneBot2 在 nonebot/init.py 中从nonebot.plugin导出，可直接from nonebot import require导入。

六大路径获取方法

加载完成后，store模块提供 6 个路径获取方法，覆盖缓存、数据、配置三类目录及对应文件：

# 获取插件缓存目录 cache_dir = store.get_plugin_cache_dir() # 获取插件缓存文件 cache_file = store.get_plugin_cache_file("file_name") # 获取插件数据目录 data_dir = store.get_plugin_data_dir() # 获取插件数据文件 data_file = store.get_plugin_data_file("file_name") # 获取插件配置目录 config_dir = store.get_plugin_config_dir() # 获取插件配置文件 config_file = store.get_plugin_config_file("file_name")

所有方法均返回pathlib.Path对象（NoneBot2 项目本身也大量使用pathlib.Path，见 nonebot/config.py 中的配置路径处理），这意味着你可以直接使用Path的完整 API。文件参数传入文件名（无需带扩展名约束，按需填写即可），目录方法不传参数。

典型读写示例：

from pathlib import Path data_file = store.get_plugin_data_file("file_name") # 写入文件内容 data_file.write_text("Hello World!") # 读取文件内容 data = data_file.read_text()

同样地，write_bytes/read_bytes可用于二进制数据，mkdir(parents=True, exist_ok=True)可用于确保目录存在后再写入，exists()可用于判断数据是否首次初始化。

使用中的两个重要注意事项

其一，Windows / macOS 下的目录合并问题。在 Windows 和 macOS 系统下，插件的数据目录和配置目录是同一个目录，因此在使用时需要注意避免文件名冲突——例如不要同时用get_plugin_data_file("settings.json")和get_plugin_config_file("settings.json")写入不同内容，否则会相互覆盖。

其二，嵌套插件目录继承。NoneBot2 支持嵌套插件，即一个插件可以在__init__.py中通过nonebot.load_plugins(...)加载子插件。对于这类嵌套插件，子插件的存储目录将位于父插件存储目录之下。这与 NoneBot2 的插件标识符设计一致：从 nonebot/plugin/model.py 源码可以看到，嵌套插件的id_属性格式为f"{self.parent_plugin.id_}:{self.name}"，即父插件标识:子插件名，插件模型通过parent_plugin与sub_plugins字段维护父子关系，存储目录的层级结构正是以此为依据生成的。

配置项详解

nonebot-plugin-localstore的所有配置项通过 NoneBot2 的环境配置体系加载：NoneBot2 使用python-dotenv与 pydantic 解析.env及.env.{environment}文件（见 nonebot/config.py），配置项大小写不敏感，因此实际书写时统一使用大写。下面逐一说明全部 7 个配置项。

localstore_use_cwd：切换到当前工作目录模式

默认值：False
作用：开启后，以当前工作目录（即运行机器人的项目目录）作为数据存储根目录，下面所有目录的默认值会相应变为<current_working_directory>/cache、<current_working_directory>/data、<current_working_directory>/config。

LOCALSTORE_USE_CWD=true

此选项适合希望数据直接跟随项目目录存放、便于备份或随项目迁移的场景。

localstore_cache_dir：自定义缓存目录

默认值：当localstore_use_cwd为True时为<current_working_directory>/cache，否则按平台：
- macOS:~/Library/Caches/nonebot2
- Unix:~/.cache/nonebot2（XDG default）
- Windows:C:\Users\<username>\AppData\Local\nonebot2\Cache

LOCALSTORE_CACHE_DIR=/tmp/cache

localstore_data_dir：自定义数据目录

默认值：当localstore_use_cwd为True时为<current_working_directory>/data，否则按平台：
- macOS:~/Library/Application Support/nonebot2
- Unix:~/.local/share/nonebot2，若定义了$XDG_DATA_HOME则使用该变量指向的目录
- Win XP (not roaming):C:\Documents and Settings\<username>\Application Data\nonebot2
- Win 7 (not roaming):C:\Users\<username>\AppData\Local\nonebot2

LOCALSTORE_DATA_DIR=/tmp/data

localstore_config_dir：自定义配置目录

默认值：当localstore_use_cwd为True时为<current_working_directory>/config，否则按平台：
- macOS: 与用户数据目录相同（即~/Library/Application Support/nonebot2）
- Unix:~/.config/nonebot2
- Win XP (roaming):C:\Documents and Settings\<username>\Local Settings\Application Data\nonebot2
- Win 7 (roaming):C:\Users\<username>\AppData\Roaming\nonebot2

LOCALSTORE_CONFIG_DIR=/tmp/config

按插件自定义的三个目录配置项

以下三项默认值均为{}，即以 JSON 对象形式按plugin_id为键、自定义路径为值，用于对特定插件单独指定目录。plugin_id即插件的索引标识（嵌套插件为父插件:子插件格式，见上文）。

LOCALSTORE_PLUGIN_CACHE_DIR=' { "plugin_id": "/tmp/plugin_cache" } '

LOCALSTORE_PLUGIN_DATA_DIR=' { "plugin_id": "/tmp/plugin_data" } '

LOCALSTORE_PLUGIN_CONFIG_DIR=' { "plugin_id": "/tmp/plugin_config" } '

需要说明的是，这三项配置值在.env文件中以 JSON 格式书写。NoneBot2 的配置解析实现（nonebot/config.py）会对复杂类型字段尝试json.loads解码，因此这些 JSON 块会被正确解析为字典；若解析失败则按字符串处理。这也意味着在实际使用时务必保证 JSON 语法正确（如使用单引号包裹、键与值均使用双引号、字符串内不含未转义的特殊字符）。

底层原理：localstore 如何与 NoneBot2 核心协同

深入理解该插件的工作方式，有助于在复杂项目中正确使用：

依赖声明链路：插件 A 通过require("nonebot_plugin_localstore")声明依赖 → NoneBot2 在 nonebot/plugin/load.py 中按"已加载 → 已声明管理器加载 → 直接加载"的优先级确保插件可用 → 返回模块对象后插件 A 才能安全 import。
路径解析链路：get_plugin_*系列方法基于当前插件上下文确定plugin_id（NoneBot2 通过 Import Hooks 记录当前正在加载的插件模块），再结合全局配置（localstore_cache_dir/data_dir/config_dir）与按插件覆盖配置（localstore_plugin_*_dir）计算出最终路径；未配置时回落到平台默认目录。
配置注入链路：所有LOCALSTORE_*配置项都经由 NoneBot2 的BaseSettings/Config体系读取（nonebot/config.py），该体系按"环境变量 > dotenv 配置文件"的优先级取值，并支持__作为嵌套分隔符与 JSON 反序列化，因此插件能够与 NoneBot2 共享同一套配置基础设施。

实战建议：一份可直接套用的最小示例

将以上内容组合起来，一个完整的"计数器插件"数据存储示例如下：

# 插件 __init__.py from pathlib import Path from nonebot import require require("nonebot_plugin_localstore") import nonebot_plugin_localstore as store # 获取并确保数据文件所在目录存在 data_file: Path = store.get_plugin_data_file("counter.json") data_file.parent.mkdir(parents=True, exist_ok=True) # 读取旧数据（不存在时返回默认值） count = int(data_file.read_text()) if data_file.exists() else 0 # 业务逻辑... count += 1 # 写回数据 data_file.write_text(str(count))

实践要点总结：

插件内统一通过store的 API 获取路径，不要硬编码相对/绝对路径；
首次写入前用mkdir(parents=True, exist_ok=True)确保目录存在；
区分缓存（可重建、可清理）与数据（必须持久化）的存放语义，分别使用 cache 与 data 系列方法；
在 Windows / macOS 上避免数据文件与配置文件同名冲突；
需要随项目迁移数据时，设置LOCALSTORE_USE_CWD=true将存储目录收敛到项目目录内；
部署到服务器（Unix）时，默认路径遵循 XDG 规范（~/.cache/nonebot2、~/.local/share/nonebot2、~/.config/nonebot2），便于与系统备份策略保持一致。