Bruno Cookie 持久化：API 测试免重复登录的完整实战
【免费下载链接】brunoOpensource IDE For Exploring and Testing API's (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno
你测过一个需要登录态的内部接口吗？——登录拿到 token 之后，Bruno 关一晚上，第二天打开还得从头走一遍登录流程。这个困扰不是 Bruno 的疏漏：它的 Cookie（维持登录状态的小型文本数据）本身就支持跨会话持久化，只是默认工作在你看不见的地方，很多功能细节需要你主动用起来。
读完本文，你能独立完成三件事：看懂 Cookie 在 Bruno 里"自动收集 → 加密落盘 → 重启恢复"的完整链路；用面板手动添加、编辑、清理任意 Cookie；在本地多环境和 CI 两种场景下让登录态稳定复用。全程不需要贴一行代码。
机制速览：Cookie 是怎么活过重启的
Bruno 的 Cookie 生命周期分四步，全部自动完成：
- 请求前注入：每次发请求前，运行时会按目标 URL 从内存中的 Cookie Jar（管理全部 Cookie 的容器）里捞出匹配项，拼进请求头，代码位置在 ipc/network/index.js。
- 响应后回收：响应头里的
set-cookie会被自动解析写回 Jar，甚至 4XX/5XX 错误响应带来的 Cookie 也不会漏掉。 - 防抖落盘：Jar 的状态按 5 秒防抖加密写入用户数据目录下的
cookies.json（Cookie 不存放在你的集合目录里，避免误提交到版本库），退出应用时会强制立即写盘，见 store/cookies.js。 - 启动时恢复：应用启动时自动把磁盘里的 Cookie 解密并重新加载回 Jar，见 index.js。
核心结论：Cookie 的持久化是"零配置"的——你不需要手动保存，只要请求跑过一遍，重启后登录态就在。真正需要理解的，是它的加密与恢复策略（下一节排障清单会讲）。
快速上手：手动管理 Cookie 的四步操作
除了自动收集，Bruno 给你留了一个手动入口——当你要"预置"一个登录态、或者清理过期 Cookie 时，用得上。
第 1 步：打开 Cookie 面板
- 操作：点击窗口底部状态栏的 Cookie 图标。
- 位置：面板入口由 StatusBar 渲染，对应选择器
data-trigger="cookies"。 - 预期效果：弹出按域名分组的 Cookie 列表；空列表时居中显示 "Add Cookie" 按钮。
第 2 步：新增一条 Cookie
- 操作：点击 "Add Cookie"，填写下表参数（也可以切到 "Edit Raw" 开关，直接粘贴
session=abc123; Domain=example.com; Path=/; Secure; HttpOnly这样的字符串）。 - 位置：表单组件在 ModifyCookieModal，面板逻辑在 Cookies/index.js。
- 预期效果：点击 Save 后，域名下立即出现新条目。
| 参数 | 说明 | 示例值 |
|---|---|---|
| domain | Cookie 绑定的域名，决定哪些请求会携带它 | example.com |
| path | 生效路径，/表示全站 | / |
| key | Cookie 名称 | session |
| value | Cookie 值，落盘时会加密 | abc123 |
| secure | 仅 HTTPS 请求携带 | 勾选 |
| httpOnly | 禁止脚本访问（与测试工具关系不大，按服务端约定勾选即可） | 勾选 |
第 3 步：验证持久化
- 操作：直接关闭 Bruno，再重新打开。
- 位置：Cookie 文件位于系统用户数据目录的
cookies.json，不随集合移动。 - 预期效果：再次打开面板，刚才的条目还在；对
example.com发请求时会自动携带。
第 4 步：清理
- 操作：对单条 Cookie 点删除图标，或对整个域名点 "Clear All"（有二次确认弹窗）。
- 位置：列表行内操作按钮，均在 Cookies 面板 内。
- 预期效果：条目即时移除，Jar 与磁盘文件同步更新。
完成这四步后，你手里就有了一个可手动干预、可重启复用的 Cookie 管理闭环——后续任何场景都是在这个闭环上叠加。
场景化进阶：三种真实用法
如果你要在本地跑多套环境
同一个接口在 dev/staging/prod 三套环境各有一个域名。Bruno 的 Cookie 按域名天然隔离——dev.api.com的登录态不会污染staging.api.com，你只需对每个环境域名各走一次"登录 + 自动收集"，之后切环境时请求会各自携带正确的 Cookie。
注意：
secure标记的 Cookie 只会在 HTTPS 请求中发送。本地环境若是http://，记得把secure去掉，否则请求静默不带 Cookie，排查起来很花时间。
你能得到的：一套环境切换零成本的多环境登录态管理，不需要在每个环境重复登录。
如果你要把登录态搬进 CI 自动化
Bruno CLI 走的是文件系统路线，与桌面端的cookies.json是两套独立存储。在 CI 里复用登录态，推荐做法是把"拿登录态"写成集合里的一个前置请求：
- 集合中放一个登录请求，响应中的
set-cookie会被 Jar 自动接收； - 后续请求依赖 Jar 中已存的 Cookie，无需手写 header；
- 登录请求失败时，用断言直接让整个运行红掉，而不是让后面的请求满屏 401。
CLI 命令入口在 bruno-cli/src/commands/，请求执行逻辑在 bruno-cli/src/runner/。
你能得到的：一个可复现的"会话自举"模式——CI 每次跑测试前自动重新登录，不依赖任何外部存储的 token。
如果你和队友共享集合
这里有一个反直觉但重要的点：cookies.json存在用户数据目录，不在集合目录里，所以它天然不会被 Git 跟踪。这不是缺陷而是设计——登录态属于个人敏感数据，跟着集合提交等于把会话发到服务器上。
正确分工是：集合（请求、断言、环境变量）进版本库共享；登录态由每人本地各自生成一次。参考仓库对这套边界的验证方式：cookie-persistence 测试、损坏密钥恢复测试。
你能得到的：团队共享集合时不会误提交敏感登录态，也不用在.gitignore里打补丁。
排障清单：五个高频问题的定位路径
1. 重启后 Cookie 值显示为空
- 现象：列表里域名和 Cookie 名都在，值却是空白。
- 原因：解密密钥不可用。加密模块（utils/encryption.js）会按 Electron SafeStorage → AES-256-CBC（以机器 ID 派生密钥）的顺序降级，系统密钥库损坏时会出现这种情况。
- 解法：重新登录一次目标服务，让 Jar 重新收集并加密写入即可；这是官方测试明确覆盖的恢复行为（值显示为空、条目保留）。
2. 请求明明带了 Cookie，服务端却说没登录
- 现象：手动加 Cookie 成功，但接口仍返回未授权。
- 原因：
secureCookie 未走 HTTPS，或 Cookie 的 domain/path 与请求 URL 不匹配。 - 解法：在 Cookie 面板确认 domain 精确匹配请求域名，本地环境去掉
secure标记。
3.cookies.json找不到或想迁移机器
- 现象：换电脑后登录态全丢。
- 原因：该文件绑定用户数据目录且密钥与本机机器 ID 相关，直接拷贝文件到另一台机器大概率解不开。
- 解法：在新机器上重新走一遍登录流程（通常 30 秒），不要试图搬运加密文件。
4. 面板里的 Cookie 和实际请求对不上
- 现象：面板显示某条 Cookie，但抓包发现请求没带它。
- 原因：已过期的 Cookie 不会发送（Jar 在取出时会过滤
expires），且已过滤的条目在部分视图下仍可见。 - 解法：删除过期条目，或等自动收集刷新它的过期时间。
5. 想"重置"但找不到重置按钮
- 现象：想清空全部 Cookie，只找到按域清理。
- 原因：Bruno 的清理粒度设计为"单条删除"和"按域名 Clear All"两个层级，没有全局一键清空。
- 解法：在面板里逐域名 Clear All；或关闭应用后直接处理用户数据目录下的
cookies.json，重启即恢复默认空状态。
你能得到的：一份按"现象 → 原因 → 解法"组织的定位表，出问题时按条目对号入座，平均 5 分钟内恢复。
延伸与协作
想深入或参与改进，入口如下：
- Cookie 存储与加密实现：packages/bruno-electron/src/store/（含 cookies.js 与 utils/encryption.js）
- 请求侧 Cookie 注入与收集：packages/bruno-electron/src/ipc/network/
- Jar 核心逻辑（基于 tough-cookie）：packages/bruno-requests/src/cookies/
- 前端 Cookie 管理面板：packages/bruno-app/src/components/Cookies/
- 端到端行为测试：tests/cookies/
- 贡献指南：contributing.md；中文文档：docs/readme/readme_cn.md
Bruno 把"登录一次，长期复用"做成了默认行为，你要做的只是看懂它、用起来。如果 Cookie 持久化中遇到本文没覆盖的场景，或想给多环境会话管理提需求，去仓库提一个 Issue 参与讨论吧。
【免费下载链接】brunoOpensource IDE For Exploring and Testing API's (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
