# 亲历踩坑：为什么使用 Next.js + RSC 一定要加 `Vary: RSC, Accept`

最近踩了一个挺有意思（却很折腾）的坑：
- 页面发版后一切看起来都对，但浏览器竟然不断去拉“看不见的 index.txt”
- 路由跳转异常，组件状态错位，甚至乱套...



原来，一切的罪魁祸首就是：**RSC payload 的缓存处理没配好**。

---

## 1. RSC 请求是怎么一回事？

在 Next.js 的 App Router + RSC 架构下，客户端导航不是直接拿 HTML，而是带个 `RSC: 1` 的请求头向服务端索取结构化 payload（也就是 `index.txt`）。普通加载（例如刷新页面）才拿回完整的 `index.html`。

也就是说，同一个 URL 可能返回两种内容：结构 payload 或者完整 HTML。它俩必须分开缓存，否则就麻烦了。

---

## 2. HTTP 的 `Vary` 是什么鬼？

> `Vary` 是个声明-response-header，告诉缓存系统（浏览器/CDN）：“要复用这条缓存，除了 URL，还得看下面这些请求头的值。”  
> 源地址：[MDN - Vary header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Vary) :contentReference[oaicite:2]{index=2}

### 为什么这很重要？

举个经典例子：服务端有 📜 GZIP 压缩版也有普通版，客户端支持 gzip 就返回压缩内容，不支持就普通内容。如果你不加，缓存就可能把压缩内容发给不支持的客户端，页面就乱套了。

Smashing Magazine 用得很直接：

> “`Vary: Accept` 就是告诉缓存——别只是看 URL，还要看 Accept。”

另外 Fastly 和 Akamai 的文章里也反复提到：`Vary` 是缓存分片的根基——没有它，同一个 URL 的不同内容会被混用，尤其 CDN 缓存

---

## 3. 那我们 RSC 场景下到底怎么处理？

由于 RSC 请求会带 `RSC: 1`，返回的是 payload，而普通访问则拿回 HTML，缓存系统得分开这俩版本。

最关键的是在响应里写上：

- `RSC: 1` + `Accept: text/plain` → `.txt`  
- 普通访问 + `Accept: text/html` → `.html` 

维护者 Tim Neutkens 在社区里也说了：

> “App Router 的目的就是告诉浏览器／CDN缓存系统：这 URL 会根据请求头变内容，所以要设 `Vary`，让缓存别乱偷。” 

---

## 4. 曾踩过的问题 & 最佳做法一览表

| 出的问题 | 原因 | 理想方案 |
|----------|------|----------|
| `.txt` 被设为长缓存（如 1 小时） | 新 HTML 发版后 `.txt` 仍是旧结构 | 将 `.txt` 和 HTML 用同样策略（no-cache）或设置短 TTL（如 5 分钟） |
| 忘加 `Vary` | CDN 直接混用 `.txt` 和 `.html`，页面结构崩 | 一定要在响应里加 `Vary: RSC, Accept` |
| JS/CSS 乱拉版本 | 静态资源中途变版本，老页面引用失效 | 用带 hash 的版本目录，静态资源单纯长缓存 |

---

## 5. 核心实战脚本（EdgeScript）

```plaintext
# 确保所有变体都携带 Vary 以避免缓存串扰
add_rsp_header('Vary', 'RSC, Accept', true)

# 放行 /homepage-data/*
if match_re($uri, '^/homepage-data/') {
    # pass
} else {

    # ===== 1) 带版本前缀：/v-<hash>(/...) =====
    if match_re($uri, '^/v-[A-Za-z0-9]{7}(/.*)?$') {

        # 恰好 /v-<hash> 或 /v-<hash>/ ：补 index.{txt|html}
        if or(match_re($uri, '^/v-[A-Za-z0-9]{7}$'), match_re($uri, '^/v-[A-Za-z0-9]{7}/$')) {
            if eq($http_RSC, '1') {
                rewrite(concat(gsub_re($uri, '^/v-', '/homepage/'), 'index.txt'), 'break')
            }
            if not(eq($http_RSC, '1')) {
                rewrite(concat(gsub_re($uri, '^/v-', '/homepage/'), 'index.html'), 'break')
            }
        } else {
            # 目录无后缀：按是否以 / 结尾补 index.{txt|html}
            if and(match_re($uri, '^/v-[A-Za-z0-9]{7}/'), not(match_re($uri, '\.[A-Za-z0-9]+$'))) {
                if match_re($uri, '/$') {
                    if eq($http_RSC, '1') {
                        rewrite(concat(gsub_re($uri, '^/v-', '/homepage/'), 'index.txt'), 'break')
                    }
                    if not(eq($http_RSC, '1')) {
                        rewrite(concat(gsub_re($uri, '^/v-', '/homepage/'), 'index.html'), 'break')
                    }
                } else {
                    if eq($http_RSC, '1') {
                        rewrite(concat(gsub_re($uri, '^/v-', '/homepage/'), '/', 'index.txt'), 'break')
                    }
                    if not(eq($http_RSC, '1')) {
                        rewrite(concat(gsub_re($uri, '^/v-', '/homepage/'), '/', 'index.html'), 'break')
                    }
                }
            } else {
                # 有后缀（含 _next/static/** 等静态资源）：仅做前缀替换
                rewrite(gsub_re($uri, '^/v-', '/homepage/'), 'break')
            }
        }

    # ===== 2) 未带版本：走 latest =====
    } else {

        # 根或 /index → 首页 index.{txt|html}
        if or(eq($uri, '/'), eq($uri, '/index'), eq($uri, '/index/')) {
            if eq($http_RSC, '1') {
                rewrite('/homepage/latest/index.txt', 'break')
            }
            if not(eq($http_RSC, '1')) {
                rewrite('/homepage/latest/index.html', 'break')
            }
        }

        # 目录（以 / 结尾且无后缀）→ 补 index.{txt|html}
        if and(match_re($uri, '/$'), not(match_re($uri, '\.[A-Za-z0-9]+$'))) {
            if eq($http_RSC, '1') {
                rewrite(concat('/homepage/latest', $uri, 'index.txt'), 'break')
            }
            if not(eq($http_RSC, '1')) {
                rewrite(concat('/homepage/latest', $uri, 'index.html'), 'break')
            }
        }

        # 非 / 结尾且无后缀 → 补 /index.{txt|html}
        if and(not(match_re($uri, '/$')), not(match_re($uri, '\.[A-Za-z0-9]+$'))) {
            if eq($http_RSC, '1') {
                rewrite(concat('/homepage/latest', $uri, '/index.txt'), 'break')
            }
            if not(eq($http_RSC, '1')) {
                rewrite(concat('/homepage/latest', $uri, '/index.html'), 'break')
            }
        }

        # 有后缀的静态资源 → 仅拼 latest 前缀
        if match_re($uri, '\.[A-Za-z0-9]+$') {
            rewrite(concat('/homepage/latest', $uri), 'break')
        }
    }
}

nextjs 生产级部署关于RSC踩坑记录

使用阿里云oss + cdn 部署静态网站

**项目目标：**
借助本工作目录及您的协助，系统性地、循序渐进地学习 Next.js，将官方文档知识转化为个人化的、易于理解和回顾的 Obsidian 笔记。





**核心参考资料：**
Next.js 官方文档 (`@NextJS`)

**工作目录结构与用途：**

如果以下目录或文件未创建，请自行创建：

- `./README.md`：(待生成) 项目介绍、学习方法、以及与您协作的指南。
- `./example/`：存放运行文档示例代码的临时空间。此目录内容可根据当前学习的示例随时覆盖更新。请注意，example 目录本身将作为一个 NextJS 项目，而非在该目录下创建新的 NextJS 项目。
- `./notes/`：(由您维护) 核心学习笔记区。采用 Markdown 格式，为 Obsidian 高度优化。
- `./prompts/`：存放我与您交互的常用提示词模板（您可以忽略，或在需要时参考以理解我的协作偏好）。

**笔记 (`./notes/`) 撰写规范：**

1. **格式：** 严格使用 Markdown 语法。
2. **Obsidian 优化：**
   &nbsp; - 充分利用 Obsidian 的扩展语法，尤其是 `[【WikiLink】]` 形式的双向链接，将相关联的 Next.js 概念、API 或模式链接起来，构建知识网络。
   &nbsp; - 合理使用标签 (`#tag`) 对笔记进行分类。
3. **内容：**
   &nbsp; - 语言精练，清晰阐述当前学习的核心知识点。原则上一份 markdown 笔记不应超过 150 行。
   &nbsp; - 包含与知识点紧密相关的**最小化**示例代码片段，而非完整项目代码。
   &nbsp; - 优先考虑原子化笔记，每个 `.md` 文件聚焦于一个具体、细分的知识点。
4. **结构：**
   &nbsp; - 根据 Next.js 知识体系，在 `./notes/` 内部创建**层级化**的子目录结构，实现精细分类。例如：`./notes/routing/`, `./notes/data-fetching/static-generation/` 等。
   &nbsp; - 单个笔记文件 (`.md`) 应保持简短，原则上不超过 150 行，鼓励拆分复杂主题。
5. **生成方式：**
   &nbsp; - 采用**迭代式**生成。每次交互仅生成或更新笔记的一小部分，反映当前讨论的知识点。
   &nbsp; - 在创建新笔记或引入新概念时，主动使用或建议 `[【WikiLink】]` 连接到已有相关笔记。

**教学与互动风格：**

1. **角色定位：** 您是一位循循善诱、经验丰富的 Next.js 编程导师。
2. **教学方法：**
   &nbsp; - **对话式教学：** 您的文本回复模拟口头讲解、引导和提问。
   &nbsp; - **笔记同步：** 在对话中涉及新知识点或代码示例时，同步更新或创建 `./notes/` 中的对应笔记文件，如同在白板上书写。
   &nbsp; - **启发式引导：** 避免直接给出完整答案。通过提问、类比、分解问题等方式引导我独立思考，促进理解。多进行互动确认我是否理解。
   &nbsp; - **短交互：** 每次输出内容精简、聚焦，保持对话的轻快节奏。避免长篇大论。我期望通过高频、简短的互动逐步深入。
   &nbsp; - **主动性：** 可根据学习进度和上下文，主动提出相关问题或建议接下来学习的内容。

**初始任务：**

请按以下顺序开始我们的学习：

1. **撰写 `./README.md`：** 基于上述项目目标和协作方式，生成项目介绍文件。
2. **撰写 `./prompts/role.md`：** 根据我期望的教学风格，为您的 AI 角色创建一个详细的 Cursor Rule 定义文件，明确您的行为准则（如：耐心、启发式、互动优先、短回复、同步笔记、使用 Obsidian 语法等）。
3. **创建教学大纲 `./catalogue.md`：**
   &nbsp; - 请**重点参考** `@NextJS` 官方文档的内容结构。
   &nbsp; - 结合 Next.js 的核心概念和学习路径，设计一份**层级清晰、结构化**的教学大纲（Markdown 格式），列出主要的学习章节和关键知识点。
   &nbsp; - 这份大纲将作为我们后续学习路线图的基础，我稍后会与您一起审阅和调整。
4. **创建第一个 NextJS 项目：** 完成上述任务后，请逐步引导我创建第一个 NextJS 项目，并在此过程中向我介绍 NextJS 的基本常识
   &nbsp; - 由于我希望将整个工作区纳入 git 管理，在创建完 NextJS 项目后，请记得删除 `./example/.git`目录
5. **开始介绍 NextJS 中的基础概念：** 项目创建完成后，你可以选择合适的切入点，开始讲解 NextJS 中的具体知识，在讲解过程中，你应该充分结合如下三种不同的教学方式：
   &nbsp; - 用简明扼要的语言直接介绍相关概念，并在必要时向用户提问
   &nbsp; - 在 `./notes/` 中提供简单的学习笔记，原则上不超过 150 行
   &nbsp; - 在 `./example/` 中以 NextJS 项目的形式提供可运行的示例代码

使用 cursor 来进行交互式学习nextjs

## nextjs 中配置SVG

nextjs 开发环境使用turbopack，需要额外配置，代码如下



```ts
const nextConfig: NextConfig = {
  webpack(config) {
    config.module.rules.push({
      test: /\.svg$/i,
      use: ["@svgr/webpack"],
    });

    return config;
  },
  experimental: {
    turbo: {
      rules: {
        "*.svg": {
          loaders: ["@svgr/webpack"],
          as: "*.js",
        },
      },
    },
  },
};
```

nextjs 中 svg 配置

在实际开发中遇到了这样的情况，公司的开发机是远程的linux机器，所有项目开发都需要通过下发的windows电脑上安装 vsocde 的 remote-ssh 工具远程连接至开发机，然后在对应的项目中开启 devServer。
最后windows 电脑上通过修改hosts文件，将域名映射到对应的服务器上的 devServer 暴漏的端口进行实时预览，方便开发和调试。例如 http://dev.xxxx.com:5173 这样即可访问。



但后端后面升级了服务，所有的 cookie 下发时都设置了secure，这样前端在开发时就就必须要为devServer配置https。前端使用的 vite ，所以直接使用 vite-plugin-mkcert 插件即可。但是需要注意，这个插件的默认配置是给localhost这个域名下发的证书，在使用时需要指定为当前服务的域名，也就是*.xxxx.com，具体配置如下：

```js
import { defineConfig } from 'vite'
import mkcert from 'vite-plugin-mkcert'
// https://vitejs.dev/config/
export default defineConfig({
  server: {
    https: true
  },
  plugins: [mkcert({
     hosts: ['*.xxxx.com']
  })]
})

```
这样配置后，使用类似 npm run dev等一些命令启动devServer时，mkcert 会自动为当前域名创建https证书，证书相关的所有文件默认都在 ~/.vite-plugin-mkcert 目录下。

先在远程开发机上找到 ~/.vite-plugin-mkcert/rootCA.pem 文件，然后将该文件下载到本地电脑(公司的win本)上
然后在本地机器上(这里是公司发的windows笔记本)按 Win + R ，输入 certmgr.msc（当前用户证书）回车后会打开证书管理器。
在左侧导航栏中，展开 ​​“受信任的根证书颁发机构”​。
右键点击 ​​“证书”​ → ​​“所有任务”​ → ​​“导入”​。
在向导中选择你的 rootCA.pem 文件，按提示完成导入。
最后浏览器强制刷新当前服务对应的页面即可。

其实总结起来一句话，由于devServer并不在本地电脑上启动，所以mkcert创建的证书不能直接被本地电脑信任。所以需要将开发机上的根证书导入并信任，这样本地电脑访问域名就不会报错：当前网站的https不安全。提高了开发体验和效率。

亲历踩坑：为什么使用 Next.js + RSC 一定要加 Vary: RSC, Accept

nextjs 中配置SVG

亲历踩坑：为什么使用 Next.js + RSC 一定要加 `Vary: RSC, Accept`