Next.js 13使用Email字样时出现服务端HTML不匹配警告

问题现象 #

在Next.js 13的客户端组件AuthForm中，当<span>标签内使用“Email”字样时，控制台抛出警告：Warning: Did not expect server HTML to contain a <div> in <label>；修改该文本后警告消失，网站其他表单使用“email”也会触发相同问题。

根本原因 #

该警告源于服务端渲染(SSR)输出的DOM结构与客户端Hydration时的DOM结构不匹配。当浏览器检测到“Email”/“email”这类表单标签文本时，自带的自动填充功能或第三方密码管理扩展会自动修改<label>内部的DOM结构，将原本的<span>替换为<div>，导致服务端输出的HTML和客户端渲染后的DOM出现差异，触发Next.js的Hydration校验警告。

解决方案 #

方案1：修改输入框自动填充属性 #

给email类型的输入框添加autoComplete="username"（将email识别为用户名，避免浏览器对email字段的特殊DOM修改）：

<label className="auth-form__label">
    <span className="auth-form__title">Email</span>
    <input
        className="auth-form__input"
        value={credentials.email}
        onChange={(e)=>setCredentials(prev=>({...prev, email:e.target.value}))}
        type="email"
        autoComplete="username" // 添加此属性
    />
</label>

若需完全禁用自动填充，也可给输入框或表单添加autoComplete="off"，但部分浏览器可能忽略该设置，优先使用autoComplete="username"更可靠。

方案2：动态设置标签文本 #

通过useEffect在客户端渲染完成后再设置“Email”文本，让服务端渲染时显示占位内容，避免DOM结构差异：

'use client'
import React, {FormEvent, useState, useEffect} from 'react';
// ... 其他导入和代码

const AuthForm = ({type}:AuthFormProps) => {
    // ... 原有state定义
    const [emailLabel, setEmailLabel] = useState("");

    useEffect(() => {
        // 客户端渲染完成后设置文本
        setEmailLabel("Email");
    }, []);

    // ... 其他函数逻辑

    return (
        <form onSubmit={onSubmit} className="auth-form">
            <label className="auth-form__label">
                <span className="auth-form__title">{emailLabel}</span> {/* 使用动态文本 */}
                <input
                    className="auth-form__input"
                    value={credentials.email}
                    onChange={(e)=>setCredentials(prev=>({...prev, email:e.target.value}))}
                    type="email"
                />
            </label>
            {/* ... 其他表单元素 */}
        </form>
    );
};

方案3：调整表单结构，分离标签与输入框 #

将可见的标题文本与关联输入框的<label>分离，避免浏览器篡改结构：

<form onSubmit={onSubmit} className="auth-form">
    <div className="auth-form__label-group">
        <span className="auth-form__title">Email</span>
        {/* 隐藏用于关联的label */}
        <label htmlFor="email-input" className="auth-form__hidden-label">Email</label>
        <input
            id="email-input"
            className="auth-form__input"
            value={credentials.email}
            onChange={(e)=>setCredentials(prev=>({...prev, email:e.target.value}))}
            type="email"
        />
    </div>
    {/* ... 其他表单元素 */}
</form>

同时在SCSS中添加隐藏label的样式：

.auth-form__hidden-label {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border-width: 0;
}

内容的提问来源于stack exchange，提问作者Jakub Godlewski