用途：指导 @jrmc/adonis-attachment 跨主版本升级，按已安装版本到目标版本逐段应用变更；也可用于从 attachment-advanced（AdonisJS 5）迁移。变更日志见 https://adonis-attachment.jrmc.dev/changelog.html。
v4→v5：移除可选包装包，直接调用二进制：npm uninstall node-poppler libreoffice-file-converter fluent-ffmpeg。重命名 bin 配置键：pdftocairoBasePath→pdftoppmPath，libreofficePaths→sofficePath。converter 选项包装变为可选，推荐扁平写法（如 thumbnail 下直接写 resize、format）。自动检测转换器为默认，可省略 converter 键，按 mime 类型路由到 image/PDF/document/video 转换器。图像转换 autoOrient 默认 true，需保留旧行为可设 autoOrient: false。v5 新增（非破坏）：router.attachments() 路由支持即时生成变体（安装 @adonisjs/lock 时使用，否则内存 verrou）；rename 选项支持函数。v5.1 新增 variant.basePath / variant.ignoreFolder 配置、attachment:variant_* 事件、AdonisJS 7 / Lucid 22 兼容。
v3→v4：无需改配置。新增（非破坏）：@attachments() 数组装饰器、createFromFiles、RegenerateService、serializeAs/自定义序列化、folder 支持路径参数或函数。
v2→v3：配置结构重做，converters 从带 key 的数组改为键控对象，并通过 InferConverters 增加类型。
v1→v2：@adonisjs/drive 变为必需：node ace add @adonisjs/drive。移除 basePath 配置，改由 config/drive.ts 中 fs 服务位置决定；为兼容 v1 存储文件可配置 fs 服务 location 为 app.publicPath()、serveFiles: true、routeBasePath: '/uploads'、visibility: 'public'。API 变为异步：getUrl()、toJSON() 需 await。序列化变体访问改为 user.avatar.thumbnail.url。
从 attachment-advanced 迁移：无自动迁移，需 node ace add @jrmc/adonis-attachment 重装，在 config/attachment.ts 重建转换器配置，数据库列保持 JSON 类型，并按 https://adonis-attachment.jrmc.dev/structure-data-json.html 校验存储的 JSON 结构。
限制：资料未提供各版本发布时间、兼容性矩阵之外的细节及回滚方案。