Skip to content

perf(serve): give app resources validators and immutable caching - #6

Merged
Patodo merged 1 commit into
mainfrom
perf/app-asset-cache-headers
Sep 18, 2026
Merged

Patodo merged 1 commit into
mainfrom
perf/app-asset-cache-headers

Conversation

@Patodo

@Patodo Patodo commented Sep 18, 2026

Copy link
Copy Markdown
Owner

针对页面加载耗时的排查结论里,平台侧那两条中的一条。

先纠正一处事实

那份报告说「静态服务代码在平台里,不在这个仓库」——不成立。应用资源的服务代码就在本仓库的 packages/server/src/routes/serve.ts/serve/:userId/:name/*),我本地跑同一份代码复现了它的观察:

资源(本机 Server,无 nginx) 修复前
应用 JS assets/index-*.js 570,538 B,Content-Encoding、无 Cache-Control、无 ETag、无 Last-Modified
应用 CSS assets/index-*.css 307,949 B,同上
平台自己的 /_next/static/*(对照) etag + cache-control: public, max-age=0

所以「每次访问重下 690 KB、连 304 都协商不了」这条是代码里的真实缺失,不是部署配置问题。

改了什么

/serve/** 下所有来自应用版本目录的文件改由同一个 helper 发送:

  • 统一带 ETag(size + mtime)与 Last-Modified
  • If-None-Match 命中 → 304
  • assets/ 下形如 <name>-<内容哈希>.<ext> 的文件 → Cache-Control: public, max-age=31536000, immutable
  • 其余(index.html,或应用自己上传的同名文件)→ Cache-Control: no-cache,每次协商

只对 assets/ 下的哈希名用 immutable 是有意的:/serve/<owner>/<app>/ 的 URL 不含版本号,若把应用自己上传的、名字恰好以短横线加长串结尾的文件也标成不可变,它在应用升级后就再也刷不新。

实测(本机安装的真实应用,同一份数据目录)

应用 JS   570,538 B 无任何验证头      ->  同内容 + immutable + ETag + Last-Modified
应用 CSS  307,949 B 无任何验证头      ->  同内容 + immutable + ETag + Last-Modified
应用 HTML                            ->  no-cache + ETag
带 If-None-Match 重发                ->  304,传输 0 字节(此前是整包重下)

新增用例 marks content-hashed app assets immutable and revalidates the resttests/integration/serve-edge.test.ts 12 项全过。

没做的那条:压缩(附证据)

压缩是首屏最大的收益(报告估算 1.83 MB → 552 KB),我实现了并加了 @fastify/compress但验证后发现它在本 Server 自己的路由上是坏的,所以回退了

fetch('http://127.0.0.1:7801/')            # 首页,我没有改过这条路由
  -> status 200, content-encoding: gzip, body length 0
curl --compressed http://127.0.0.1:7801/owner/app1/  -> 0 字节
加 Accept-Encoding: identity                          -> 9047 字节(正常)

同一个客户端取 /_next/static/*@fastify/static 的文件路径)能正常解出 173,217 字节,说明不是客户端问题,而是插件与本 Server 自建路由的交互问题(packages/serverserver-core 里都没有其他 onSend/serializer 钩子)。带上它会让服务端测试从 14 条失败涨到 23 条(含全部 shell/serve 渲染用例)。所以我没提交这个依赖。

压缩的可行路径:你们部署前面就有 nginx,在那层开 gzip/brotli 是纯配置改动、零代码风险,也是这份报告最初的建议;如果希望由 Server 自带(容器镜像里没有代理层),需要在插件交互上单独排查一次,我可以另开 issue 跟进。

未涉及

报告里的第三条(应用是「fetch 完再注入」的串行关键路径)属于架构选型,我没有动。

App version files were sent with only a CSP header: no Cache-Control, no ETag,
no Last-Modified, while the Platform Shell's own /_next/static assets already
had them. A hashed bundle under /serve/<owner>/<app>/assets/ therefore could not
be cached or revalidated, so every visit re-downloaded it in full — a 570 KB
bundle and a 308 KB stylesheet measured on one real app.

Serve files from an app version directory through one helper that sets an ETag
and Last-Modified, answers 304 on a matching If-None-Match, and marks a
Vite-style content-hashed asset under assets/ immutable. Anything else
(index.html, or a file the app itself shipped) keeps its name across versions,
so it stays 'no-cache' and revalidates.

Measured against a locally installed app on the shipped build:

  app JS  570,538 B, no validators  ->  same bytes + immutable + ETag
  app CSS 307,949 B, no validators  ->  same bytes + immutable + ETag
  app HTML                           ->  no-cache + ETag, revalidates as 304
  repeat request with If-None-Match  ->  304, 0 bytes (was a full re-download)
@Patodo
Patodo merged commit 9578d1c into main Sep 18, 2026
5 of 7 checks passed
Patodo added a commit that referenced this pull request Sep 18, 2026
Ships the served-app caching fix from #6: app version files now carry an ETag
and Last-Modified, answer 304 on revalidation, and mark a content-hashed asset
under assets/ immutable, instead of re-downloading the whole bundle on every
visit.

Version-bound test assertions move to 0.2.8 and the reviewed public source
baseline digests are re-recorded for the two files this touches. The flagged
content in both files is unchanged: the same three canonical package markers
and the same apiKey fixture as before.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant