fix(assets): rewrite service worker with two-strategy caching (#774)

- Replace legacy service-worker.js (imported from DoIt) with a clean rewrite using Hugo's ExecuteAsTemplate for fingerprinted URL injection - Cache-first for static assets (immutable/fingerprinted), network-first for HTML pages with LRU eviction (max 100 entries) - Fix LRU eviction to protect precached URLs using absolute URL comparison - Add Fingerprint param to js-build.html partial to reduce boilerplate - Extract to-css.html partial for reusable SCSS-to-CSS pipeline - Support pre-built Resource param in script.html and style.html - Store mainCSS and mainJS in Site.Store to avoid duplicate builds - Remove explicit scope from serviceWorker.register() (defaults to /) Closes #298
2026-08-24 15:28:57 +00:00 · 2026-05-31 17:54:02 +08:00
parent 03d81f0785
commit 17164f42d0
11 changed files with 278 additions and 332 deletions
@@ -290,12 +290,16 @@

 {{- /* PWA */ -}}
 {{- if not hugo.IsServer | and .Site.Params.enablePWA | and hugo.IsProduction -}}
-  {{- $serviceWorker := dict "Resource" (resources.Get "js/service-worker.js") "Build" true | partial "function/js-build.html" -}}
-  {{- with $fingerprint -}}
-    {{- $serviceWorker = $serviceWorker | fingerprint . -}}
+  {{- $offlineURL := "" -}}
+  {{- with .Site.Home.OutputFormats.Get "offline" -}}
+    {{- $offlineURL = .RelPermalink -}}
  {{- end -}}
-  {{- $serviceWorkerURL := $serviceWorker.RelPermalink -}}
-  {{- $config = dict "PWA" (dict "enable" .Site.Params.enablePWA "serviceWorkerURL" $serviceWorkerURL) | merge $config -}}
+  {{- $mainCSS := .Site.Store.Get "mainCSS" -}}
+  {{- $mainJS := .Site.Store.Get "mainJS" -}}
+  {{- $swBuildCtx := dict "mainCSSURL" $mainCSS.RelPermalink "mainJSURL" $mainJS.RelPermalink "offlineURL" $offlineURL "relURL" (relURL "") "Page" . -}}
+  {{- $serviceWorker := resources.Get "js/service-worker.template.js" | resources.ExecuteAsTemplate "js/service-worker.template.js" $swBuildCtx -}}
+  {{- $serviceWorker = dict "Resource" $serviceWorker "Build" (dict "targetPath" "sw.js") "Fingerprint" $fingerprint | partial "function/js-build.html" -}}
+  {{- $config = dict "PWA" (dict "enable" .Site.Params.enablePWA "serviceWorkerURL" $serviceWorker.RelPermalink) | merge $config -}}
 {{- end -}}

 {{- /* Auto Bookmark */ -}}
@@ -366,10 +370,7 @@
  {{- $layoutLoaders := $mermaid.layoutloaders | default slice -}}

  {{- $options := dict "format" "esm" -}}
-  {{- $mermaidModule := dict "Resource" (resources.Get "js/lib/mermaid.ts") "Build" $options | partial "function/js-build.html" -}}
-  {{- with $fingerprint -}}
-    {{- $mermaidModule = $mermaidModule | fingerprint . -}}
-  {{- end -}}
+  {{- $mermaidModule := dict "Resource" (resources.Get "js/lib/mermaid.ts") "Build" $options "Fingerprint" $fingerprint | partial "function/js-build.html" -}}
  {{- $mermaidModuleURL := $mermaidModule.RelPermalink -}}

  {{- $bootstrapJS := dict
@@ -384,8 +385,8 @@
  {{- dict "Content" $bootstrapJS "Path" "js/lib/mermaid-bootstrap.js" "Minify" hugo.IsProduction "Attr" `type="module"` "Defer" true | dict "Page" . "Data" | partial "store/script.html" -}}
 {{- end -}}

-{{- /* Theme main bundle */ -}}
-{{- dict "Source" "js/main.ts" "Build" true "Fingerprint" $fingerprint "Defer" true | dict "Page" . "Data" | partial "store/script.html" -}}
+{{- /* Theme main bundle (built once in head/index.html) */ -}}
+{{- dict "Resource" (.Site.Store.Get "mainJS") "Defer" true | dict "Page" . "Data" | partial "store/script.html" -}}

 {{- /* Custom assets block */ -}}
 {{- block "custom-assets" . }}{{ end -}}
@@ -75,8 +75,7 @@
  {{- $title = .Site.Title -}}
 {{- end -}}

-{{- /* Favicon links */ -}}
-{{/* [todo] 先判断有图片资源时才加载，没有时提示引导 https://realfavicongenerator.net/  */}}
+{{- /* Favicon links (static resources, generated via https://realfavicongenerator.net/) */ -}}
 {{- if not .Site.Params.app.noFavicon -}}
  {{- $relURL := relURL "" -}}
  {{- with .Site.Params.app.svgFavicon -}}
@@ -125,12 +124,14 @@
 -}}

 {{- /* Theme main CSS */ -}}
-{{- dict
-  "Source" "scss/main.scss"
+{{- $mainCSS := dict
+  "Resource" (resources.Get "scss/main.scss")
  "ToCSS" true
  "Fingerprint" $fingerprint
-  | partial "plugin/style.html"
+  | partial "function/to-css.html"
 -}}
+{{- .Site.Store.Set "mainCSS" $mainCSS -}}
+{{- dict "Resource" $mainCSS | partial "plugin/style.html" -}}

 {{- /* Font Awesome Icons */ -}}
 {{- $source := $cdn.fontawesomeFreeCSS | default "lib/fontawesome-free/all.min.css" -}}
@@ -143,10 +144,8 @@
 {{- partial "plugin/style.html" $options -}}

 {{- /* Preload main theme bundle */ -}}
-{{- $mainResource := dict "Resource" (resources.Get "js/main.ts") "Build" true | partial "function/js-build.html" -}}
-{{- with $fingerprint -}}
-  {{- $mainResource = $mainResource | fingerprint . -}}
-{{- end -}}
+{{- $mainResource := dict "Resource" (resources.Get "js/main.ts") "Build" true "Fingerprint" $fingerprint | partial "function/js-build.html" -}}
+{{- .Site.Store.Set "mainJS" $mainResource -}}
 <link rel="preload" href="{{ $mainResource.RelPermalink }}" as="script">

 {{- /* ========== SEO: Structured Data (Schema.org) ========== */ -}}
@@ -3,6 +3,7 @@
  @param {resource.Resource} .Resource Hugo resource to process
  @param {Object|Boolean} [.Build] true for defaults, dict for custom options, false/omit to skip js.Build
  @param {Boolean} [.Minify] extra minify flag; final minify is Minify OR Build.minify
+  @param {String} [.Fingerprint] fingerprint algorithm (e.g. "sha256")
  @return {resource.Resource}
 */ -}}

@@ -25,4 +26,7 @@
 {{- if $minify -}}
  {{- $resource = $resource | minify -}}
 {{- end -}}
+{{- with .Fingerprint -}}
+  {{- $resource = $resource | fingerprint . -}}
+{{- end -}}
 {{- return $resource -}}
@@ -0,0 +1,35 @@
+{{- /*
+  Compile SCSS to CSS via dartsass, optionally minify and fingerprint.
+  @param {resource.Resource} .Resource SCSS resource
+  @param {Object|Boolean} [.ToCSS] true for defaults, dict for custom toCSS options, false/omit to skip
+  @param {Boolean} [.Minify] whether to minify; defaults to hugo.IsProduction when ToCSS is used
+  @param {String} [.Fingerprint] fingerprint algorithm (e.g. "sha256")
+  @return {resource.Resource}
+*/ -}}
+
+{{- $resource := .Resource -}}
+{{- $minify := .Minify -}}
+{{- with .ToCSS -}}
+  {{- $targetPath := replaceRE `\.(template\.)?scss$` ".css" $resource.Name -}}
+  {{- $targetPath = replace $targetPath "scss" "css" -}}
+  {{- $defaultOptions := dict
+    "transpiler" "dartsass"
+    "enableSourceMap" hugo.IsDevelopment
+    "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+    "targetPath" $targetPath
+  -}}
+  {{- $options := . -}}
+  {{- if eq $options true -}}
+    {{- $options = dict -}}
+  {{- end -}}
+  {{- $options = $options | merge $defaultOptions -}}
+  {{- $resource = $resource | toCSS $options -}}
+  {{- $minify = $minify | default hugo.IsProduction -}}
+{{- end -}}
+{{- if $minify -}}
+  {{- $resource = $resource | minify -}}
+{{- end -}}
+{{- with .Fingerprint -}}
+  {{- $resource = $resource | fingerprint . -}}
+{{- end -}}
+{{- return $resource -}}
@@ -1,8 +1,9 @@
 {{- /*
  Script tag renderer.
-  - Accepts direct script HTML or builds script source from local/remote resources.
+  - Accepts direct script HTML, a pre-built resource, or builds from source path.
  - Supports template execution, minify/build/fingerprint pipeline, and extra attrs.
-  @param {String|Resource} .Source script source URL/path or Hugo resource; if string starts with "<script" it's treated as raw HTML
+  @param {String} [.Source] script source URL/path; if starts with "<script" it's treated as raw HTML
+  @param {resource.Resource} [.Resource] pre-built resource (skips build pipeline)
  @param {String} [.Content] inline content to write as generated resource
  @param {String} [.Path] target path for resource created from Content
  @param {Object} [.Template] target path for resource created from template execution
@@ -17,21 +18,31 @@
  @param {String} [.Attr] additional attributes
 */ -}}

-{{- if strings.HasPrefix .Source "<script" -}}
+{{- if strings.HasPrefix (.Source | default "") "<script" -}}
  {{- safeHTML .Source -}}
 {{- else -}}
-  {{- /* Script source */ -}}
-  {{- $src := .Source -}}
+  {{- $src := "" -}}
  {{- $integrity := .Integrity -}}
-  {{- $minify := .Minify -}}
-  {{- if $src | and (not (urls.Parse $src).Host) -}}
+
+  {{- /* Pre-built resource */ -}}
+  {{- with .Resource -}}
+    {{- $src = .RelPermalink -}}
+    {{- with .Data.Integrity -}}
+      {{- $integrity = . -}}
+    {{- end -}}
+  {{- end -}}
+
+  {{- /* Source build */ -}}
+  {{- if not $src -}}
+    {{- $src = .Source -}}
+  {{- end -}}
+  {{- if $src | and (not (urls.Parse $src).Host) | and (not .Resource) -}}
    {{- $resource := resources.Get $src -}}
    {{- with .Template -}}
      {{- $resource = resources.ExecuteAsTemplate . $.Context $resource -}}
    {{- end -}}
-    {{- $resource = dict "Resource" $resource "Build" .Build "Minify" $minify | partial "function/js-build.html" -}}
+    {{- $resource = dict "Resource" $resource "Build" .Build "Minify" .Minify "Fingerprint" .Fingerprint | partial "function/js-build.html" -}}
    {{- with .Fingerprint -}}
-      {{- $resource = $resource | fingerprint . -}}
      {{- $integrity = $resource.Data.Integrity -}}
    {{- end -}}
    {{- with $resource.RelPermalink -}}
@@ -1,8 +1,9 @@
 {{- /*
  Stylesheet tag renderer.
-  - Accepts direct <link> HTML or builds CSS resources from local paths/content.
+  - Accepts direct <link> HTML, a pre-built resource, or builds from source path.
  - Supports template execution, optional toCSS, minify/fingerprint, and preload mode.
-  @param {String} .Source stylesheet URL/path or Hugo resource; if string starts with "<link" it's treated as raw HTML
+  @param {String} [.Source] stylesheet URL/path; if starts with "<link" it's treated as raw HTML
+  @param {resource.Resource} [.Resource] pre-built resource (skips build pipeline)
  @param {String} [.Content] inline style content to write as generated resource
  @param {String} [.Path] target path for resource created from Content
  @param {Object} [.Template] target path for resource created from template execution
@@ -16,50 +17,46 @@
  @param {String} [.Attr] additional attributes
 */ -}}

-{{- if strings.HasPrefix .Source "<link" -}}
+{{- if strings.HasPrefix (.Source | default "") "<link" -}}
  {{- safeHTML .Source -}}
 {{- else -}}
-  {{- $href := .Source -}}
+  {{- $href := "" -}}
  {{- $integrity := .Integrity -}}
-  {{- $resource := 0 -}}
-  {{- if $href | and (not (urls.Parse $href).Host) -}}
-    {{- $resource = resources.Get $href -}}
+
+  {{- /* Pre-built resource */ -}}
+  {{- with .Resource -}}
+    {{- $href = .RelPermalink -}}
+    {{- with .Data.Integrity -}}
+      {{- $integrity = . -}}
+    {{- end -}}
  {{- end -}}
-  {{- with .Content -}}
-    {{- $resource = resources.FromString $.Path . -}}
+
+  {{- /* Source build */ -}}
+  {{- if not $href -}}
+    {{- $href = .Source -}}
  {{- end -}}
-  {{- if $resource -}}
-    {{- $minify := .Minify -}}
+  {{- if $href | and (not (urls.Parse $href).Host) | and (not .Resource) -}}
+    {{- $resource := resources.Get $href -}}
    {{- with .Template -}}
      {{- $resource = resources.ExecuteAsTemplate . $.Context $resource -}}
    {{- end -}}
-    {{- with .ToCSS -}}
-      {{- $targetPath := replaceRE `\.(template\.)?scss$` ".css" $resource.Name -}}
-      {{- $targetPath = replace $targetPath "scss" "css" -}}
-      {{- $defaultOptions := dict
-        "transpiler" "dartsass"
-        "enableSourceMap" hugo.IsDevelopment
-        "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
-        "targetPath" $targetPath
-        "silenceDeprecations" (slice "import" "global-builtin" "color-functions" "function-units")
-      -}}
-      {{- $options := . -}}
-      {{- if eq . true -}}
-        {{- $options = dict -}}
-      {{- end -}}
-      {{- $options = $options | merge $defaultOptions -}}
-      {{- $resource = $resource | toCSS $options -}}
-      {{- $minify = $minify | default hugo.IsProduction -}}
-    {{- end -}}
-    {{- if $minify -}}
-      {{- $resource = $resource | minify -}}
-    {{- end -}}
+    {{- $resource = dict "Resource" $resource "ToCSS" .ToCSS "Minify" .Minify "Fingerprint" .Fingerprint | partial "function/to-css.html" -}}
    {{- with .Fingerprint -}}
-      {{- $resource = $resource | fingerprint . -}}
      {{- $integrity = $resource.Data.Integrity -}}
    {{- end -}}
    {{- $href = $resource.RelPermalink -}}
  {{- end -}}
+
+  {{- /* Style from string */ -}}
+  {{- if .Content | and .Path -}}
+    {{- $contentResource := resources.FromString .Path .Content -}}
+    {{- if .Minify -}}
+      {{- $contentResource = $contentResource | minify -}}
+    {{- end -}}
+    {{- $href = $contentResource.RelPermalink -}}
+  {{- end -}}
+
+  {{- /* Style attributes */ -}}
  {{- $attrs := printf `href="%v"` $href -}}
  {{- if .Crossorigin -}}
    {{- $attrs = ` crossorigin="anonymous"` | add $attrs -}}