feat(image-cache): 新增图片本地缓存并全站接入

引入 cached-image 组件与 image-cache 工具，实现签名 URL 稳定 key 剥离、downloadFile 落盘及 TTL/LRU 清理，替换 11 个页面与 clothes-card 共 22 处网络图片渲染点，减少 CDN 重复流量。
2026-09-26 19:49:54 +08:00
parent 7cd6c169c2
commit f169777f4a
30 changed files with 754 additions and 25 deletions
@@ -0,0 +1,165 @@
+---
+name: 图片本地缓存方案
+overview: 为小程序新增图片本地文件缓存机制（签名 URL 稳定 key 剥离 + downloadFile 落盘 + TTL/LRU 治理），封装 cached-image 组件并替换全项目所有网络图片渲染点，显著降低 CDN 重复流量。
+todos:
+  - id: create-image-cache
+    content: 新建 utils/image-cache.ts：稳定 key、双哈希落盘、并发队列去重、失败回退熔断、TTL 容量清扫
+    status: completed
+  - id: create-cached-image
+    content: 新建 components/cached-image 组件：占位后显示本地文件，透传 mode/lazy-load，布局与圆角零回归
+    status: completed
+    dependencies:
+      - create-image-cache
+  - id: replace-images
+    content: 替换 11 个页面与 clothes-card 共 22 处 image 并注册组件，逐处核对 mode 与 lazy-load 保持原样
+    status: completed
+    dependencies:
+      - create-cached-image
+  - id: verify-coverage
+    content: Use [subagent:code-explorer] 全仓复核网络图片接入无遗漏，本地临时图与包内素材未受影响
+    status: completed
+    dependencies:
+      - replace-images
+  - id: typecheck-lint
+    content: 运行 TS 严格类型检查与 lint，修复新增/改动文件问题，复查日志级别使用合规
+    status: completed
+    dependencies:
+      - replace-images
+---
+
+## 产品概述
+
+为现有微信小程序（衣橱与穿搭社区）新增统一的图片本地缓存机制：网络图片首次加载后自动下载并持久化到本地，后续展示直接读取本地文件，避免图片被反复从 CDN 拉取，从源头降低流量。
+
+## 核心功能
+
+- 两级缓存：内存映射 + 本地文件持久化，自动完成下载、落盘与命中读取
+- 签名地址兼容：按剥离签名/时间戳参数后的稳定地址命中缓存，地址参数每次变化也不再重复下载
+- 省流量展示：缓存未命中时先显示骨架占位（复用现有骨架风格），下载完成后显示本地图片；每张图仅向 CDN 请求一次
+- 失败兜底：下载失败自动回退为网络地址显示；下载域名未配置时自动熔断，功能完全不受影响
+- 全站覆盖：衣橱、穿搭社区、AI 推荐、分享详情、个人资料等约 22 处网络图片统一接入
+- 自动清理：按有效期与容量上限自动淘汰旧缓存，避免占满本地空间
+- 视觉零变化：除短暂骨架占位外，图片尺寸、圆角、裁剪模式、懒加载表现与现状完全一致
+
+## 现状与根因
+
+- 全仓 22 处网络图片（头像、抠图衣物图、分享封面、拼图封面等）均直接绑定接口返回 URL 渲染，无任何本地缓存逻辑（已全仓检索 downloadFile / FileSystemManager / 预加载，均无结果）。
+- 图片 URL 为带签名/时间戳的临时链接且每次请求会变化；微信 image 组件按「完整 URL（含 query）」做客户端缓存、CDN 也按 URL 缓存，签名一变即双双失效，导致同一张图被反复下载。
+- wxss 中的 url(...) 均为内联 SVG，无 CSS 网络背景图；无 canvas 绘制、无保存到相册场景，改造面收敛在 image 标签内。
+
+## 技术方案（Implementation Approach）
+
+采用「核心缓存模块 + 通用图片组件」的前端两级缓存方案，落地路径如下：
+
+1. 新增 `utils/image-cache.ts`（与 UI 无关的纯逻辑模块，通过 logger 输出日志）：
+
+- 稳定 key：剥离大小写不敏感的签名类参数（sign/signature/sig/t/ts/timestamp/time/expires/expire/auth/token/nonce/x-cos-security-token/q-sign-time 等，清单在模块头部集中维护并注释），其余 query 排序后与 host+path 拼接；保证「同一张图即使签名变化」也命中同一缓存条目。
+- 落盘指纹：不引入任何依赖，自实现 FNV-1a + djb2 双 32 位哈希拼接为 16 位十六进制文件名（降低碰撞概率），扩展名从 URL pathname 提取（jpg/png/webp/gif，缺省 .jpg）。
+- 存储位置：`${wx.env.USER_DATA_PATH}/imgcache/`（本地用户文件，随代码包清理，生命周期与代码包一致，安全可靠；总量上限 200MB，本方案自设 80MB 上限留足余量）。
+- 命中判定：内存 Map（O(1)）→ `fs.access`（异步）判断磁盘文件 → 均未命中才进入下载。
+- 下载：`wx.downloadFile` 指定 `filePath` 直写目标文件（先惰性 mkdir 递归创建目录）；并发队列上限 4；同一稳定 key 的任务去重（复用同一 Promise）；statusCode 非 200 视为失败并删除半截文件。
+- 失败与熔断：单图失败仅 debug 日志并让组件回退网络地址；若失败信息包含「url not in domain list」（downloadFile 合法域名未配置），会话级熔断禁用缓存流程，warn 一次（写实时日志）后全部直接回退原逻辑。
+- 容量治理（异步、不阻塞渲染）：TTL 7 天 + 容量 80MB / 300 个文件，超出时按文件 mtime 从旧到新删除；清扫节流触发（启动后首次图片解析 5 秒执行一次，运行期内每累计约 50 次成功落盘再执行一次），执行中不重复触发；文件删除失败忽略。
+
+2. 新增 `components/cached-image` 通用图片组件（替换原 image 标签）：
+
+- 属性：`src`（网络地址或本地路径）、`mode`（默认 aspectFill）、`lazyLoad`（wxml 用 lazy-load 传入，默认 false，保持各调用点原行为）。
+- 流程：src 非 https（wxfile://、http://tmp、http://usr 等本地临时/包内路径）直接渲染不进入缓存；https 地址先查内存/磁盘，命中直接显示本地文件（全程零网络请求）；未命中显示骨架占位并进入下载队列，成功后显示本地文件。
+- 关键约束：占位与下载期间绝不渲染原始网络 URL，避免 image 组件自发请求抵消缓存收益；仅下载失败后回退渲染网络地址，保证功能可用。
+- 自愈：内层 image 触发 error 且当前为本地路径时，删除该缓存文件并回退网络地址一次（应对文件被系统清理）。
+- 样式兼容（零布局回归）：组件 wxss 用 `:host { display: inline-block; }` 对齐原 image 元素默认布局行为，内层 image `width/height: 100%; display: block; border-radius: inherit` 保证填满宿主并继承圆角；调用点原有 class（.pic 等尺寸体系）、mode、lazy-load 原样保留，class 落在组件宿主节点上，无需改动任何现有 wxss。
+
+3. 接入范围：11 个页面 wxml + clothes-card 组件共 22 处 image 标签替换为 cached-image，并沿用现有注册惯例（`"cached-image": "/components/cached-image/cached-image"`）在对应页面/组件 json 的 usingComponents 中注册；wardrobe 页经 clothes-card 间接生效，upload 页本地预览、damo 包内素材、图标等一律不动。
+
+## 系统架构
+
+```mermaid
+flowchart LR
+  A[cached-image 组件收到 src] --> B{是否 https 网络图?}
+  B -- 否 --> C[直接渲染本地路径]
+  B -- 是 --> D{内存命中?}
+  D -- 是 --> E[显示本地文件]
+  D -- 否 --> F{磁盘已存在?}
+  F -- 是 --> E
+  F -- 否 --> G[并发队列 downloadFile 落盘]
+  G -- 成功 --> E
+  G -- 失败 --> H[回退显示网络 URL]
+```
+
+## 目录结构
+
+```
+zt-closet-wxmini-frontend/miniprogram/
+├── utils/
+│   └── image-cache.ts                  # [NEW] 缓存核心：稳定 key 剥离、双哈希文件名、内存+磁盘命中、
+│                                       #       downloadFile 并发队列与去重、失败回退与域名熔断、
+│                                       #       TTL/容量清扫、logger 日志（LOG='image-cache'）
+├── components/
+│   ├── cached-image/
+│   │   ├── cached-image.ts             # [NEW] 组件逻辑：属性定义、src 监听、本地/网络分流、占位与回退、
+│   │   │                               #       出错自愈（删坏文件并回退网络地址）
+│   │   ├── cached-image.wxml           # [NEW] 占位层 + 内层 image（mode/lazy-load 透传）
+│   │   ├── cached-image.wxss           # [NEW] :host 布局对齐、内层 100% 填充与 border-radius 继承、
+│   │   │                               #       骨架占位（对齐现有 .sk 视觉，局部 keyframes）
+│   │   └── cached-image.json           # [NEW] { "component": true }
+│   └── clothes-card/
+│       ├── clothes-card.wxml           # [MODIFY] 1 处 image（衣物瓦片，lazy-load 保留）
+│       └── clothes-card.json           # [MODIFY] 注册 cached-image
+├── pages/
+│   ├── outfit/                         # [MODIFY] outfit.wxml 4 处 + outfit.json 注册
+│   ├── ai-recommend/                   # [MODIFY] ai-recommend.wxml 2 处 + json 注册
+│   ├── outfit-detail/                  # [MODIFY] outfit-detail.wxml 2 处 + json 注册
+│   ├── outfit-edit/                    # [MODIFY] outfit-edit.wxml 1 处 + json 注册
+│   ├── outfit-share-detail/            # [MODIFY] outfit-share-detail.wxml 3 处 + json 注册
+│   ├── closet-share/                   # [MODIFY] closet-share.wxml 2 处（封面/头像）+ json 注册
+│   ├── closet-share-create/            # [MODIFY] closet-share-create.wxml 1 处（头像）+ json 注册
+│   ├── closet-share-detail/            # [MODIFY] closet-share-detail.wxml 2 处 + json 注册
+│   ├── ai-pending/                     # [MODIFY] ai-pending.wxml 1 处（封面格）+ json 注册
+│   ├── profile/                        # [MODIFY] profile.wxml 2 处（头像）+ json 注册
+│   └── clothes-detail/                 # [MODIFY] clothes-detail.wxml 1 处（详情大图）+ json 注册
+```
+
+不改动：pages/wardrobe（经 clothes-card 生效）、pages/upload（本地临时图预览）、damo 素材、custom-tab-bar、全局样式、config.ts、接口层与所有 .ts 业务逻辑。
+
+## 关键代码结构
+
+```ts
+// miniprogram/utils/image-cache.ts —— 对外接口（仅签名）
+/** 内存命中快速通道：命中返回本地路径，否则 null（供组件首帧零延迟显示） */
+export function getCachedLocalPath(src: string): string | null
+
+/** 解析图片：磁盘命中直接返回本地路径；未命中入队下载落盘后返回；失败 reject（调用方回退网络地址） */
+export function resolveImage(src: string): Promise&lt;string&gt;
+
+/** 手动清空图片缓存目录（预留维护入口） */
+export function clearImageCache(): Promise&lt;void&gt;
+```
+
+组件属性约定：`src: String`；`mode: String = 'aspectFill'`；`lazyLoad: Boolean = false`（wxml 以 `lazy-load` 传入）。
+
+## 实施注意（Implementation Notes）
+
+- 占位/下载期间严禁渲染网络 URL（核心防漏点）；仅下载失败回退。
+- 缓存范围判定统一为「仅 https 开头的地址进入缓存流程」，天然兼容真机与开发者工具的本地路径（wxfile://、http://tmp、http://usr）。
+- 文件系统操作全部用异步 API（access/mkdir/unlink/readdir/stat），仅内存 Map 同步；清扫异步执行且去重，避免主线程卡顿。
+- downloadFile 并发 ≤4 且同 key 任务合并，防止列表页瞬时大量图片同时下载。
+- 日志复用 `utils/logger.ts`：debug 记命中/miss/落盘与清扫摘要，warn 仅一次用于域名未配置熔断；不输出签名 URL 原文，只输出稳定 key 或哈希文件名，保护实时日志配额。
+- 零新增依赖：双哈希自实现；TS strict（noUnusedLocals/noImplicitAny）下编写；注释保持项目现有中文风格。
+- 需在微信公众平台「开发设置-服务器域名」配置 **downloadFile 合法域名**（图片 CDN 域名）；开发者工具本地验证可勾选「不校验合法域名」。
+
+## 验证与上线
+
+1. 首次冷启动进入衣橱/AI 穿搭：先占位后出图，日志呈现 miss → download → saved。
+2. 返回重进或杀进程重进：日志 hit（内存/磁盘），Network 面板无同图请求。
+3. 列表刷新后签名参数变化：仍命中本地缓存（稳定 key 生效）。
+4. 头像、拼图封面、详情大图、分享封面视觉零变化（圆角、aspectFill/Fit、lazy-load）。
+5. 模拟域名未配置：自动熔断回退网络图，页面功能正常。
+6. `npx tsc --noEmit`（或开发者工具编译）无类型错误，read_lints 无新增告警。
+
+## Agent Extensions
+
+### SubAgent
+
+- **code-explorer**
+- Purpose: 在全部替换完成后，对 miniprogram 目录做一轮全仓交叉复核，确认所有网络图片使用点均已接入 cached-image、无遗漏或误改（含 wardrobe 经 clothes-card 的间接使用、upload 本地预览与 damo 包内素材未受影响）。
+- Expected outcome: 输出完整的图片使用点核对清单与结论，明确 22 处替换全覆盖、无残留的网络 image 标签，作为验收依据。
@@ -0,0 +1,4 @@
+{
+  "component": true,
+  "styleIsolation": "isolated"
+}
@@ -0,0 +1,77 @@
+// cached-image —— 通用图片组件：网络图经 utils/image-cache 落盘后展示（命中时零网络请求），
+// 本地路径（wxfile:// / http://tmp / 包内路径等）原样直出；
+// 未命中缓存时先骨架占位、下载完成后显示本地文件，失败自动回退网络地址，功能不受影响。
+
+import { getCachedLocalPath, resolveImage, dropImageCache } from '../../utils/image-cache'
+
+Component({
+  properties: {
+    src: { type: String, value: '' },
+    // 与 image 组件对齐：未显式传入时保持 scaleToFill 默认行为
+    mode: { type: String, value: 'scaleToFill' },
+    lazyLoad: { type: Boolean, value: false },
+  },
+  data: {
+    // 实际渲染地址：本地文件路径或回退的网络地址；空串 = 骨架占位中
+    shown: '',
+  },
+  observers: {
+    src() {
+      this.refresh()
+    },
+  },
+  lifetimes: {
+    attached() {
+      ;(this as any)._alive = true
+      this.refresh()
+    },
+    detached() {
+      ;(this as any)._alive = false
+    },
+  },
+  methods: {
+    refresh() {
+      const src = this.data.src
+      const seq = (((this as any)._seq as number) || 0) + 1
+      ;(this as any)._seq = seq
+
+      if (!src) {
+        this.setData({ shown: '' })
+        return
+      }
+      if (src.indexOf('https://') !== 0) {
+        // 本地/包内路径直接渲染，不进入缓存流程
+        this.setData({ shown: src })
+        return
+      }
+      const hit = getCachedLocalPath(src)
+      if (hit) {
+        this.setData({ shown: hit })
+        return
+      }
+      // 未命中：先占位，下载落盘后显示本地文件（期间不渲染网络地址，避免额外请求抵消缓存收益）
+      if (this.data.shown) this.setData({ shown: '' })
+      resolveImage(src).then(
+        (localPath) => {
+          if ((this as any)._alive === false || (this as any)._seq !== seq) return
+          this.setData({ shown: localPath })
+        },
+        () => {
+          if ((this as any)._alive === false || (this as any)._seq !== seq) return
+          // 缓存不可用时回退网络地址，保证功能可用
+          this.setData({ shown: src })
+        }
+      )
+    },
+    onImgError() {
+      const shown = this.data.shown
+      const src = this.data.src
+      // 网络地址自身失败或非网络图：不再处理，避免循环回退
+      if (!shown || !src || shown.indexOf('https://') === 0) return
+      ;(this as any)._seq = (((this as any)._seq as number) || 0) + 1
+      // 本地文件失效（被系统清理/损坏）：清理缓存并回退网络地址一次
+      dropImageCache(src)
+      this.setData({ shown: src })
+    },
+  },
+})
@@ -0,0 +1,10 @@
+<!-- 通用图片：缓存命中直出本地文件，未命中先骨架占位，失败回退网络地址 -->
+<view wx:if="{{!shown}}" class="ci-ph"></view>
+<image
+  wx:if="{{shown}}"
+  class="ci-img"
+  src="{{shown}}"
+  mode="{{mode}}"
+  lazy-load="{{lazyLoad}}"
+  binderror="onImgError"
+/>
@@ -0,0 +1,26 @@
+/* 宿主节点：对齐 image 组件默认 inline-block 布局，尺寸与圆角由调用方 class 控制 */
+:host {
+  display: inline-block;
+  overflow: hidden;
+}
+
+/* 内层图片：填满宿主并继承圆角，保证既有版式零回归 */
+.ci-img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+}
+
+/* 骨架占位：与全局 .sk 同款视觉，组件内独立定义避免依赖外部样式加载顺序 */
+.ci-ph {
+  width: 100%;
+  height: 100%;
+  background: linear-gradient(90deg, #F2F2F0 25%, #E9E9E6 37%, #F2F2F0 63%);
+  background-size: 400% 100%;
+  animation: ciSkLoad 1.5s ease infinite;
+}
+@keyframes ciSkLoad {
+  0% { background-position: 100% 50%; }
+  100% { background-position: 0 50%; }
+}
@@ -1,4 +1,7 @@
 {
  "component": true,
-  "styleIsolation": "apply-shared"
+  "styleIsolation": "apply-shared",
+  "usingComponents": {
+    "cached-image": "/components/cached-image/cached-image"
+  }
 }
@@ -1,12 +1,12 @@
 <!-- v2 衣物瓦片：无卡片容器，图下两行（衬线品名 + 灰色属性行） -->
 <view class="tile {{selected ? 'is-picked' : ''}}" bindtap="onTap">
  <view class="tile-img">
-    <image
+    <cached-image
      wx:if="{{item.processed_image}}"
      class="pic"
      src="{{item.processed_image}}"
      mode="aspectFill"
-      lazy-load
+      lazy-load="{{true}}"
    />
    <view wx:else class="ph icon icon-hanger"></view>
    <view wx:if="{{statusText}}" class="tile-flag {{statusType === 'ink' ? 'is-ink' : ''}}">{{statusText}}</view>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -63,7 +63,7 @@
        <!-- 无缝拼图封面 -->
        <view class="collage {{item._collageCls}}">
          <view class="cg" wx:for="{{item._covers}}" wx:for-item="c" wx:key="k">
-            <image wx:if="{{c.img}}" class="pic" src="{{c.img}}" mode="aspectFill" lazy-load />
+            <cached-image wx:if="{{c.img}}" class="pic" src="{{c.img}}" mode="aspectFill" lazy-load="{{true}}" />
            <view wx:else class="ph icon icon-hanger"></view>
          </view>
          <view wx:if="{{item._moreCount > 0}}" class="cg-more">+{{item._moreCount}}</view>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -44,7 +44,7 @@ module.exports = { cls: cls }
    <view class="ai-cover">
      <view class="collage {{cl.cls(clothes.length)}}">
        <view class="cg" wx:for="{{clothes}}" wx:key="clothes_uuid" wx:if="{{index < 4}}">
-          <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+          <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
          <view wx:else class="ph icon icon-hanger"></view>
        </view>
        <view wx:if="{{clothes.length > 4}}" class="cg-more">+{{clothes.length - 4}}</view>
@@ -77,7 +77,7 @@ module.exports = { cls: cls }
        <view class="ai-items-row">
          <view class="ai-chip" wx:for="{{clothes}}" wx:key="clothes_uuid">
            <view class="ai-thumb">
-              <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+              <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
              <view wx:else class="ph icon icon-hanger"></view>
            </view>
            <text class="ai-chip-n">{{item.name || '未命名'}}</text>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "clothes-card": "/components/clothes-card/clothes-card",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -95,7 +95,7 @@
    <view class="csc-preview">
      <view class="csc-preview-hd">
        <view class="csc-av">
-          <image wx:if="{{avatar}}" class="pic" src="{{avatar}}" mode="aspectFill" />
+          <cached-image wx:if="{{avatar}}" class="pic" src="{{avatar}}" mode="aspectFill" />
          <view wx:else class="icon icon-user"></view>
        </view>
        <text class="csc-preview-n">{{nickname}} 向你分享了 {{selectedCount || '全部'}} 件衣物</text>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -28,7 +28,7 @@

    <view class="csd-owner">
      <view class="csd-av">
-        <image wx:if="{{detail.owner_avatar}}" class="pic" src="{{detail.owner_avatar}}" mode="aspectFill" />
+        <cached-image wx:if="{{detail.owner_avatar}}" class="pic" src="{{detail.owner_avatar}}" mode="aspectFill" />
        <view wx:else class="icon icon-user"></view>
      </view>
      <view class="csd-owner-body">
@@ -41,7 +41,7 @@
    <view class="csd-grid">
      <view class="csd-tile" wx:for="{{detail.clothes}}" wx:key="clothes_uuid">
        <view class="tile-img">
-          <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" lazy-load />
+          <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" lazy-load="{{true}}" />
          <view wx:else class="ph icon icon-hanger"></view>
        </view>
        <view class="tile-name">{{item.name || '未命名'}}</view>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state"
  }
 }
@@ -59,13 +59,13 @@
        </view>
        <!-- 穿搭分享：封面 -->
        <view class="cs-thumb is-photo" wx:else>
-          <image wx:if="{{item.cover}}" class="pic" src="{{item.cover}}" mode="aspectFill" />
+          <cached-image wx:if="{{item.cover}}" class="pic" src="{{item.cover}}" mode="aspectFill" />
          <view wx:else class="ph icon icon-hanger"></view>
        </view>

        <view class="cs-body">
          <view class="cs-owner" wx:if="{{activeTab === 1}}">
-            <image wx:if="{{item.owner_avatar}}" class="oav" src="{{item.owner_avatar}}" mode="aspectFill" />
+            <cached-image wx:if="{{item.owner_avatar}}" class="oav" src="{{item.owner_avatar}}" mode="aspectFill" />
            <view wx:else class="oav">
              <view class="icon icon-user"></view>
            </view>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -110,7 +110,7 @@ module.exports = { hex: hex, tags: tags }
    <block wx:else>
      <!-- 大图：买手店目录式线稿/实拍 -->
      <view class="cd-photo">
-        <image
+        <cached-image
          wx:if="{{detail.processed_image}}"
          class="pic"
          src="{{detail.processed_image}}"
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -57,7 +57,7 @@ module.exports = { cls: cls }
      <view class="od-cover">
        <view class="collage {{cl.cls(clothes.length)}}">
          <view class="cg" wx:for="{{clothes}}" wx:key="clothes_uuid" wx:if="{{index < 4}}">
-            <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+            <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
            <view wx:else class="ph icon icon-hanger"></view>
          </view>
          <view wx:if="{{clothes.length > 4}}" class="cg-more">+{{clothes.length - 4}}</view>
@@ -100,7 +100,7 @@ module.exports = { cls: cls }
              bindtap="onItemTap"
            >
              <view class="od-thumb">
-                <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+                <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
                <view wx:else class="ph icon icon-hanger"></view>
              </view>
              <text class="od-chip-n">{{item.name || '未命名'}}</text>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "clothes-card": "/components/clothes-card/clothes-card",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -32,7 +32,7 @@ module.exports = { cls: cls }
        bindtap="openSelect"
      >
        <view class="cg" wx:for="{{selectedItems}}" wx:key="clothes_uuid" wx:if="{{index < 4}}">
-          <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+          <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
          <view wx:else class="ph icon icon-hanger"></view>
        </view>
        <view wx:if="{{selectedItems.length > 4}}" class="cg-more">+{{selectedItems.length - 4}}</view>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state",
    "v2-overlay": "/components/v2-overlay/index"
  }
@@ -38,7 +38,7 @@ module.exports = { cls: cls }

    <view class="osd-owner">
      <view class="osd-av">
-        <image wx:if="{{detail.owner_avatar}}" class="pic" src="{{detail.owner_avatar}}" mode="aspectFill" />
+        <cached-image wx:if="{{detail.owner_avatar}}" class="pic" src="{{detail.owner_avatar}}" mode="aspectFill" />
        <view wx:else class="icon icon-user"></view>
      </view>
      <view class="osd-owner-body">
@@ -51,7 +51,7 @@ module.exports = { cls: cls }
    <view class="osd-cover">
      <view class="collage {{cl.cls(outfit.items.length)}}">
        <view class="cg" wx:for="{{outfit.items}}" wx:key="clothes_uuid" wx:if="{{index < 4}}">
-          <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+          <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
          <view wx:else class="ph icon icon-hanger"></view>
        </view>
        <view wx:if="{{outfit.items.length > 4}}" class="cg-more">+{{outfit.items.length - 4}}</view>
@@ -84,7 +84,7 @@ module.exports = { cls: cls }
            bindtap="onItemTap"
          >
            <view class="osd-thumb">
-              <image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
+              <cached-image wx:if="{{item.processed_image}}" class="pic" src="{{item.processed_image}}" mode="aspectFill" />
              <view wx:else class="ph icon icon-hanger"></view>
            </view>
          </view>
@@ -1,6 +1,7 @@
 {
  "usingComponents": {
    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image",
    "empty-state": "/components/empty-state/empty-state"
  }
 }
@@ -68,7 +68,7 @@
      <view class="of-card" bindtap="onGuestOutfitTap">
        <view class="collage collage--2">
          <view class="cg" wx:for="{{guestOutfit.items}}" wx:key="clothes_uuid">
-            <image class="pic" src="{{item.processed_image}}" mode="aspectFit" />
+            <cached-image class="pic" src="{{item.processed_image}}" mode="aspectFit" />
          </view>
        </view>
        <view class="of-trow">
@@ -98,7 +98,7 @@
      >
        <!-- 作者行：仅社区分段 -->
        <view class="of-author" wx:if="{{activeTab === 2}}">
-          <image wx:if="{{item.owner_avatar}}" class="of-av" src="{{item.owner_avatar}}" mode="aspectFill" />
+          <cached-image wx:if="{{item.owner_avatar}}" class="of-av" src="{{item.owner_avatar}}" mode="aspectFill" />
          <view wx:else class="of-av">
            <view class="icon icon-user"></view>
          </view>
@@ -109,7 +109,7 @@
        <!-- 无缝拼图封面（_covers 由 outfitCover 组装，缺失时整体不渲染，避免 1:1 空白方块撑满屏幕） -->
        <view wx:if="{{item._covers}}" class="collage {{item._collageCls}}">
          <view class="cg" wx:for="{{item._covers}}" wx:for-item="c" wx:key="k">
-            <image wx:if="{{c.img}}" class="pic" src="{{c.img}}" mode="aspectFill" lazy-load />
+            <cached-image wx:if="{{c.img}}" class="pic" src="{{c.img}}" mode="aspectFill" lazy-load="{{true}}" />
            <view wx:else class="ph icon icon-hanger"></view>
          </view>
          <view wx:if="{{item._moreCount > 0}}" class="cg-more">+{{item._moreCount}}</view>
@@ -172,7 +172,7 @@
        <view class="gd-items">
          <view class="gd-item" wx:for="{{guestOutfit.items}}" wx:key="clothes_uuid">
            <view class="gd-item-img">
-              <image class="pic" src="{{item.processed_image}}" mode="aspectFit" />
+              <cached-image class="pic" src="{{item.processed_image}}" mode="aspectFit" />
            </view>
            <view class="tile-name">{{item.name}}</view>
            <view class="tile-sub">{{item.category_main}}{{item.category_sub ? ' · ' + item.category_sub : ''}}</view>
@@ -1,5 +1,6 @@
 {
  "usingComponents": {
-    "navigation-bar": "/components/navigation-bar/navigation-bar"
+    "navigation-bar": "/components/navigation-bar/navigation-bar",
+    "cached-image": "/components/cached-image/cached-image"
  }
 }
@@ -27,7 +27,7 @@
    <!-- 资料区：大号头像 + 衬线昵称 + 胶囊标签 -->
    <view wx:else class="pf-hero">
      <view class="pf-av">
-        <image wx:if="{{userInfo.avatar}}" class="pf-av-img" src="{{userInfo.avatar}}" mode="aspectFill" />
+        <cached-image wx:if="{{userInfo.avatar}}" class="pf-av-img" src="{{userInfo.avatar}}" mode="aspectFill" />
        <view wx:else class="icon icon-user"></view>
      </view>
      <view class="pf-info">
@@ -150,7 +150,7 @@

      <view class="sheet-body">
        <view class="avatar-wrap">
-          <image wx:if="{{editForm.avatar}}" class="avatar-img" src="{{editForm.avatar}}" mode="aspectFill" />
+          <cached-image wx:if="{{editForm.avatar}}" class="avatar-img" src="{{editForm.avatar}}" mode="aspectFill" />
          <view wx:else class="icon icon-user avatar-placeholder"></view>
          <button class="avatar-btn" open-type="chooseAvatar" bindchooseavatar="onChooseAvatar"></button>
        </view>
@@ -0,0 +1,433 @@
+// 图片本地缓存：网络图片首次展示时下载落盘，后续直接复用本地文件，减少 CDN 重复流量。
+// 背景：接口返回的图片是带签名/时间戳的临时 URL，每次请求都会变化；微信 image 自带的
+//       缓存按「完整 URL（含 query）」记录，签名一变即失效，同一张图会被反复下载。
+//       本模块按「剥离签名参数后的稳定地址」作为缓存 key 落盘，同一张图只请求 CDN 一次。
+//
+// 命中链路：内存 Map → 磁盘文件 → downloadFile 落盘（并发 ≤4、同 key 任务去重）。
+// 失败处理：单图失败由组件回退网络地址；检测到 downloadFile 域名未配置时整会话熔断，
+//           避免继续发起必然失败的请求。
+// 空间治理：TTL + 容量上限，空闲时异步清扫，不阻塞渲染。
+
+import { logger } from './logger'
+
+// 日志模块名
+const LOG = 'image-cache'
+
+// 缓存目录（本地用户文件，随小程序代码包生命周期清理）
+const CACHE_DIR = `${wx.env.USER_DATA_PATH}/imgcache`
+// 过期时间：超过 7 天未修改的缓存文件优先淘汰
+const TTL_MS = 7 * 24 * 60 * 60 * 1000
+// 目录容量上限：本地文件总量上限约 200MB，自设 80MB 留足业务余量
+const MAX_BYTES = 80 * 1024 * 1024
+// 文件数量上限
+const MAX_FILES = 300
+// 内存映射上限，超出时整体重建（后续重新走磁盘命中，代价可控）
+const MAX_MEM_ENTRIES = 500
+// downloadFile 并发上限（微信侧总上限 10，留余量给业务请求）
+const MAX_CONCURRENCY = 4
+// 清扫延迟：首次解析后延迟执行，避免与首屏图片加载抢资源
+const PRUNE_DELAY_MS = 5000
+// 运行期每成功落盘 50 张再触发一次清扫
+const PRUNE_EVERY_SAVES = 50
+
+// 签名类参数名（小写，集中维护）：签名 URL 每次返回都不同，必须从缓存 key 中剥离，否则永远无法命中
+const SIGN_PARAMS = new Set([
+  // 通用签名 / 时间戳
+  'sign',
+  'signature',
+  'sig',
+  't',
+  'ts',
+  'timestamp',
+  'time',
+  'expires',
+  'expire',
+  'auth',
+  'token',
+  'nonce',
+  // 腾讯云 COS
+  'authorize',
+  'x-cos-security-token',
+  'q-sign-algorithm',
+  'q-sign-time',
+  'q-key-time',
+  'q-signature',
+  'q-header-list',
+  'q-url-param-list',
+  // 阿里云 OSS
+  'ossaccesskeyid',
+  'security-token',
+  'auth_key',
+  // AWS S3 / CloudFront
+  'x-signature',
+  'x-amz-algorithm',
+  'x-amz-credential',
+  'x-amz-date',
+  'x-amz-expires',
+  'x-amz-signature',
+  'x-amz-security-token',
+  'x-amz-signedheaders',
+  'key-pair-id',
+  'policy',
+])
+
+// ===== 运行状态 =====
+
+// 稳定 key → 本地文件路径（内存快速通道）
+const memCache = new Map<string, string>()
+// 稳定 key → 进行中的下载任务（并发复用，避免同一张图重复下载）
+const inflight = new Map<string, Promise<string>>()
+// 下载域名未配置等不可恢复失败的会话级熔断
+let disabled = false
+// 缓存目录就绪状态与初始化 Promise
+let dirReady = false
+let dirPromise: Promise<void> | null = null
+// downloadFile 并发闸门
+let running = 0
+const waiters: Array<() => void> = []
+// 清扫节流状态
+let firstPruneDone = false
+let pruneScheduled = false
+let savesSincePrune = 0
+
+function fs(): WechatMiniprogram.FileSystemManager {
+  return wx.getFileSystemManager()
+}
+
+// 仅 https 网络图进入缓存流程；本地路径（wxfile:// / http://tmp / http://usr / 包内路径）原样返回
+function isRemote(src: string): boolean {
+  return src.indexOf('https://') === 0
+}
+
+// ===== 稳定 key 与文件指纹 =====
+
+// 剥离签名/时间戳参数，其余 query 排序后与 host+path 拼接；同一张图签名变化也命中同一缓存
+function stableKey(src: string): string {
+  const idx = src.indexOf('?')
+  if (idx < 0) return src
+  const base = src.slice(0, idx)
+  const kept: string[] = []
+  for (const part of src.slice(idx + 1).split('&')) {
+    if (!part) continue
+    const eq = part.indexOf('=')
+    const rawKey = (eq >= 0 ? part.slice(0, eq) : part).toLowerCase()
+    let name = rawKey
+    try {
+      name = decodeURIComponent(rawKey)
+    } catch (e) {
+      // 参数名解码失败按原样处理
+    }
+    if (SIGN_PARAMS.has(name)) continue
+    kept.push(part)
+  }
+  if (!kept.length) return base
+  kept.sort()
+  return `${base}?${kept.join('&')}`
+}
+
+function hex32(n: number): string {
+  return ('00000000' + (n >>> 0).toString(16)).slice(-8)
+}
+
+// FNV-1a 32 位：不引入依赖的快速哈希
+function fnv1a(str: string): string {
+  let h = 0x811c9dc5
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return hex32(h)
+}
+
+// djb2 32 位：与 FNV-1a 拼接为 16 位十六进制文件名，降低碰撞概率
+function djb2(str: string): string {
+  let h = 5381
+  for (let i = 0; i < str.length; i++) {
+    h = (Math.imul(h, 33) + str.charCodeAt(i)) >>> 0
+  }
+  return hex32(h)
+}
+
+function hashKey(key: string): string {
+  return fnv1a(key) + djb2(key)
+}
+
+// 扩展名取自 URL 路径，白名单外统一按 .jpg 处理（仅影响本地文件名，不影响渲染）
+function extOf(src: string): string {
+  const path = src.split('?')[0].split('#')[0]
+  const m = /\.(jpg|jpeg|png|webp|gif)$/i.exec(path)
+  if (!m) return '.jpg'
+  const ext = m[1].toLowerCase()
+  return ext === 'jpeg' ? '.jpg' : `.${ext}`
+}
+
+function localPathOf(key: string, src: string): string {
+  return `${CACHE_DIR}/${hashKey(key)}${extOf(src)}`
+}
+
+// ===== 文件系统操作（全部异步包装，失败静默由调用方决定兜底） =====
+
+function ensureDir(): Promise<void> {
+  if (dirReady) return Promise.resolve()
+  if (!dirPromise) {
+    dirPromise = new Promise<void>((resolve) => {
+      fs().mkdir({
+        dirPath: CACHE_DIR,
+        recursive: true,
+        success: () => resolve(),
+        // 目录已存在等失败一律放行，落盘失败会在下载阶段回退
+        fail: () => resolve(),
+      })
+    }).then(() => {
+      dirReady = true
+    })
+  }
+  return dirPromise
+}
+
+function accessFile(path: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    fs().access({
+      path,
+      success: () => resolve(true),
+      fail: () => resolve(false),
+    })
+  })
+}
+
+function unlinkQuiet(path: string): Promise<void> {
+  return new Promise((resolve) => {
+    fs().unlink({
+      filePath: path,
+      success: () => resolve(),
+      fail: () => resolve(),
+    })
+  })
+}
+
+function readdir(): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    fs().readdir({
+      dirPath: CACHE_DIR,
+      success: (res) => resolve(res.files || []),
+      fail: (err) => reject(new Error((err && err.errMsg) || 'readdir fail')),
+    })
+  })
+}
+
+function statFile(path: string): Promise<{ size: number; mtime: number } | null> {
+  return new Promise((resolve) => {
+    fs().stat({
+      path,
+      success: (res) => {
+        const s = res.stats
+        if (typeof s.isFile === 'function' && !s.isFile()) {
+          resolve(null)
+          return
+        }
+        // 官方单位是秒，但个别端返回毫秒，统一归一化为毫秒
+        const raw = Number(s.lastModifiedTime) || 0
+        const mtime = raw > 1e11 ? raw : raw * 1000
+        resolve({ size: Number(s.size) || 0, mtime })
+      },
+      fail: () => resolve(null),
+    })
+  })
+}
+
+// ===== 下载：并发闸门 + 直写目标文件 =====
+
+function acquireSlot(): Promise<void> {
+  if (running < MAX_CONCURRENCY) {
+    running++
+    return Promise.resolve()
+  }
+  return new Promise((resolve) => {
+    waiters.push(() => {
+      running++
+      resolve()
+    })
+  })
+}
+
+function releaseSlot(): void {
+  running--
+  const next = waiters.shift()
+  if (next) next()
+}
+
+function download(url: string, filePath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    wx.downloadFile({
+      url,
+      filePath,
+      success: (res) => {
+        if (res.statusCode === 200) resolve()
+        else reject(new Error(`http ${res.statusCode}`))
+      },
+      fail: (err) => reject(new Error((err && err.errMsg) || 'download fail')),
+    })
+  })
+}
+
+// ===== 空闲清扫：TTL 过期 + 超容量/超数量按最旧优先删除 =====
+
+async function pruneCache(): Promise<void> {
+  try {
+    const names = await readdir()
+    const now = Date.now()
+    const alive: Array<{ path: string; size: number; mtime: number }> = []
+    let expired = 0
+
+    for (const name of names) {
+      const path = `${CACHE_DIR}/${name}`
+      const st = await statFile(path)
+      if (!st) continue
+      if (now - st.mtime > TTL_MS) {
+        await unlinkQuiet(path)
+        expired++
+        continue
+      }
+      alive.push({ path, size: st.size, mtime: st.mtime })
+    }
+
+    alive.sort((a, b) => a.mtime - b.mtime)
+    let bytes = 0
+    for (const it of alive) bytes += it.size
+    let removed = 0
+    let i = 0
+    while (i < alive.length && (bytes > MAX_BYTES || alive.length - i > MAX_FILES)) {
+      await unlinkQuiet(alive[i].path)
+      bytes -= alive[i].size
+      removed++
+      i++
+    }
+
+    logger.debug(LOG, 'prune done, total=', names.length, 'expired=', expired, 'overflow=', removed)
+  } catch (e) {
+    // 目录尚未创建等情况直接跳过，不重试不报错
+    logger.debug(LOG, 'prune skipped')
+  }
+}
+
+function notePrune(): void {
+  // 首次解析后延迟清扫一次
+  if (!firstPruneDone && !pruneScheduled) {
+    pruneScheduled = true
+    setTimeout(runPrune, PRUNE_DELAY_MS)
+  }
+}
+
+function noteSaved(): void {
+  savesSincePrune++
+  // 运行期累计落盘后再触发一次
+  if (firstPruneDone && !pruneScheduled && savesSincePrune >= PRUNE_EVERY_SAVES) {
+    pruneScheduled = true
+    setTimeout(runPrune, PRUNE_DELAY_MS)
+  }
+}
+
+function runPrune(): void {
+  pruneCache().then(() => {
+    firstPruneDone = true
+    savesSincePrune = 0
+    pruneScheduled = false
+  })
+}
+
+// ===== 对外接口 =====
+
+function memSet(key: string, localPath: string): void {
+  if (memCache.size >= MAX_MEM_ENTRIES) memCache.clear()
+  memCache.set(key, localPath)
+}
+
+/** 内存命中快速通道：命中返回本地路径，否则 null（供组件首帧零延迟直出） */
+export function getCachedLocalPath(src: string): string | null {
+  if (!src || !isRemote(src) || disabled) return null
+  return memCache.get(stableKey(src)) || null
+}
+
+async function loadOrDownload(key: string, src: string): Promise<string> {
+  const localPath = localPathOf(key, src)
+  const id = hashKey(key)
+
+  if (await accessFile(localPath)) {
+    logger.debug(LOG, 'hit disk', id)
+    return localPath
+  }
+
+  await ensureDir()
+  await acquireSlot()
+  try {
+    await download(src, localPath)
+    noteSaved()
+    logger.debug(LOG, 'saved', id)
+    return localPath
+  } catch (e) {
+    // 清理可能残留的半截文件，交由组件回退网络地址
+    await unlinkQuiet(localPath)
+    const msg = e instanceof Error ? e.message : String(e)
+    if (!disabled && /not in domain list/i.test(msg)) {
+      disabled = true
+      logger.warn(LOG, 'downloadFile 域名未配置，停用图片缓存并回退网络图（请在小程序后台配置 downloadFile 合法域名）')
+    } else {
+      logger.debug(LOG, 'download fail, fallback network, id=', id, 'reason=', msg)
+    }
+    throw e
+  } finally {
+    releaseSlot()
+  }
+}
+
+/** 解析图片：磁盘命中直接返回本地路径；未命中入队下载落盘后返回；失败 reject（调用方回退网络地址） */
+export function resolveImage(src: string): Promise<string> {
+  if (!src || !isRemote(src)) return Promise.resolve(src)
+  if (disabled) return Promise.reject(new Error('image cache disabled'))
+
+  const key = stableKey(src)
+  const hit = memCache.get(key)
+  if (hit) {
+    logger.debug(LOG, 'hit mem', hashKey(key))
+    return Promise.resolve(hit)
+  }
+
+  const pending = inflight.get(key)
+  if (pending) return pending
+
+  notePrune()
+
+  const task = loadOrDownload(key, src).then(
+    (localPath) => {
+      memSet(key, localPath)
+      inflight.delete(key)
+      return localPath
+    },
+    (err) => {
+      inflight.delete(key)
+      throw err
+    }
+  )
+  inflight.set(key, task)
+  return task
+}
+
+/** 删除某个网络图对应的本地缓存（组件自愈用：本地文件损坏时清理后回退网络地址） */
+export function dropImageCache(src: string): void {
+  if (!src || !isRemote(src)) return
+  const key = stableKey(src)
+  const localPath = memCache.get(key) || localPathOf(key, src)
+  memCache.delete(key)
+  unlinkQuiet(localPath).then(() => undefined)
+}
+
+/** 清空全部图片缓存（预留维护入口） */
+export function clearImageCache(): Promise<void> {
+  memCache.clear()
+  return readdir()
+    .then((names) => Promise.all(names.map((name) => unlinkQuiet(`${CACHE_DIR}/${name}`))))
+    .then(() => {
+      logger.debug(LOG, 'clear done')
+    })
+    .catch(() => undefined)
+}