Next.js 14：首次调用revalidateTag为何触发全量刷新？

通过客户端组件的Server Action修改数据后调用revalidateTag重新获取数据时，首次渲染后的第一次重验证会重置所有客户端状态（类似全量刷新），但后续重验证可正常保留客户端状态。测试中router.refresh、revalidateTag、revalidatePath均出现相同现象。

测试场景：

• page.tsx作为服务端组件获取并展示数据
• 子客户端组件包含表单（通过Server Action修改数据）和用于观察状态的计数器
• 操作步骤：先递增计数器，再提交表单
• 现象：第一次提交时数据更新但计数器重置为0；后续提交数据更新且计数器状态保留

根据Next.js文档，revalidateTag应仅重新渲染服务端组件并合并新数据，不影响无关客户端状态，首次重验证的异常行为不符合预期。

测试代码 #

app/test/page.tsx #

import { API_MACHINE_GET_DETAILS } from "../api/azure/Machines/apiRoutes";
import { MachineDetails } from "../utils/interfaces";
import Client from "./client";

export default async function Page() {
    const id = '13502294-e057-4001-ac3f-3cc0132742b4';
    const url = `${API_MACHINE_GET_DETAILS}?id=${id}`

    // fetch and display data
    const response = await fetch(url, {
        method: 'GET',
        cache: 'no-cache'
    });
    const jsonData = await response.json();
    const machineDetails: MachineDetails = jsonData;

    return (
        <div>
            <h1>{machineDetails.displayName}</h1>
            <Client />
        </div>
    );
}

app/test/client.tsx #

'use client';

import { useState } from "react";
import { updateMachine } from "../actions/apiUtils";

export default function Client() {
    // client side state which should not be reset
    const [counter, setCounter] = useState(0);

    return (
        <div style={{ display: "flex", flexDirection: 'column' }}>
            <p>client state: {counter}</p>
            <button onClick={() => setCounter(counter + 1)}>Increment</button>
            <form action={updateMachine}>
                <input type="text" name="displayName" />
                <button type="submit">Update Machine</button>
            </form>
        </div >
    );
}

app/actions/apiUtils.ts #

'use server';

import { ApiResponse } from "@/app/utils/interfaces";
import { revalidateTag } from "next/cache";
import { API_MACHINE_UPDATE } from "../api/azure/Machines/apiRoutes";

const API_ERROR_MESSAGE = 'Error sending request. Please notify your administrator for assistance.';

async function updateMachine(formData: FormData): Promise<ApiResponse> {
    'use server';

    formData.append('id', '13502294-e057-4001-ac3f-3cc0132742b4');
    formData.append('machineNumber', '1234');

    try {
        const response = await fetch(API_MACHINE_UPDATE, {
            method: 'PUT',
            body: formData,
        });
        const jsonData = await response.json();
        if (response.ok) {
            revalidateTag('api'); // revalidation
            return { status: response.status, message: jsonData.message };
        }
        return { status: response.status, message: jsonData.message || API_ERROR_MESSAGE };
    } catch (error) {
        return { status: 500, message: API_ERROR_MESSAGE };
    }
}

export { updateMachine };

原因与解决方案 #

原因 #

首次重验证时出现客户端状态重置，是因为页面初始渲染时没有为服务端组件的请求添加缓存标签，导致revalidateTag('api')触发时，Next.js无法精准定位需要更新的服务端组件，进而触发了全页面刷新（包括客户端组件的状态重置）。后续请求因为缓存机制已经建立，所以能正常局部更新。

解决步骤 #

1. 为服务端组件的fetch请求添加标签：在page.tsx的fetch调用中加入next: { tags: ['api'] }配置，让Next.js将该请求与api标签关联：

const response = await fetch(url, {
    method: 'GET',
    cache: 'no-cache',
    next: { tags: ['api'] } // 添加缓存标签
});

2. 确保Server Action中的revalidateTag与请求标签一致：当前代码中已经使用revalidateTag('api')，这一步保持不变即可。

原理说明 #

添加标签后，Next.js能精准识别需要重新验证的服务端请求，仅重新渲染关联的服务端组件并更新页面数据，不会影响客户端组件的状态。首次重验证时，因为请求已经绑定了标签，Next.js无需触发全页面刷新，客户端状态自然得以保留。

内容的提问来源于stack exchange，提问作者Iain Black