Cloudflare Turnstile与Remix集成异常问题排查求助

问题现象 #

• 首次加载页面提交表单时，收到错误提示：The provided Turnstile token was not valid!
• 页面闲置一段时间后刷新，Turnstile 部件会加载完成并显示绿色对勾，此时表单可正常提交
• 首次加载时，对Cloudflare API的请求处于pending状态：https://challenges.cloudflare.com/cdn-cgi/challenge-platform/h/b/flow/ov1/xxx:xxx:xxx/xxx/xxx；刷新页面后该请求成功，验证码加载完成

原因分析 #

1. 脚本加载时机不匹配：当前使用async+defer加载Turnstile脚本，脚本可能在表单渲染完成后才加载完毕，导致首次加载时Turnstile未完成验证流程，提交的token无效。
2. 自动初始化失效：依赖脚本自动初始化验证部件，但在Remix的服务端渲染场景下，DOM节点可能晚于脚本加载完成，导致自动初始化逻辑未触发，无法生成有效token。
3. 无提交拦截机制：用户可在Turnstile验证完成前提交表单，此时token尚未生成或处于无效状态。

解决方案 #

1. 调整脚本加载策略 + 显式初始化验证部件 #

取消脚本的async和defer属性，确保脚本加载完成后再渲染DOM；或添加手动初始化逻辑，保证验证部件正确生成：

修改脚本加载代码

let scripts: ExternalScriptsFunction<SerializeFrom<typeof loader>> = () => {
    return [
        {
            src: "https://challenges.cloudflare.com/turnstile/v0/api.js",
            async: false,
            defer: false
        },
    ];
};

组件内添加显式初始化逻辑

import { useEffect, useState } from 'react';

const Contact = (props: Props) => {
    const { TURNSTILE_SITE_KEY } = useLoaderData<typeof loader>()
    const response = useActionData<typeof action>()

    useEffect(() => {
        if (window.turnstile && TURNSTILE_SITE_KEY) {
            window.turnstile.render('.cf-turnstile', {
                sitekey: TURNSTILE_SITE_KEY,
                theme: 'light',
                callback: (token) => {
                    // 验证完成后可启用提交按钮
                    document.querySelector('button[type="submit"]')?.removeAttribute('disabled');
                }
            });
        }
    }, [TURNSTILE_SITE_KEY]);

    // 原有组件代码...
}

2. 拦截表单提交，确保验证完成后再允许提交 #

禁用提交按钮，直到Turnstile验证完成，避免用户提前提交：

const Contact = (props: Props) => {
    const { TURNSTILE_SITE_KEY } = useLoaderData<typeof loader>()
    const response = useActionData<typeof action>()
    const [isVerified, setIsVerified] = useState(false);

    useEffect(() => {
        if (window.turnstile && TURNSTILE_SITE_KEY) {
            window.turnstile.render('.cf-turnstile', {
                sitekey: TURNSTILE_SITE_KEY,
                theme: 'light',
                callback: () => setIsVerified(true),
                "error-callback": () => setIsVerified(false)
            });
        }
    }, [TURNSTILE_SITE_KEY]);

    // 原有JSX代码...
    <button
        type="submit"
        disabled={!isVerified}
        className="ml-3 inline-block rounded-lg bg-blue-500 px-5 py-3 text-sm font-medium text-white disabled:opacity-50 disabled:cursor-not-allowed"
    >
        Message
    </button>
    // 原有JSX代码...
}

3. 修正后端验证逻辑，优化数据传递 #

新建独立的FormData用于Turnstile验证，避免污染原表单数据，同时可选添加用户IP提升验证准确性：

export async function action({ request }: ActionArgs) {
    const formData = await request.formData();
    const token = formData.get('cf-turnstile-response') as string;
    
    // 新建FormData用于验证请求
    const verifyFormData = new FormData();
    verifyFormData.append('secret', process.env.TURNSTILE_SECRET_KEY!);
    verifyFormData.append('response', token);
    // 可选：添加用户IP，增强验证精度
    const remoteIp = request.headers.get('CF-Connecting-IP') || request.headers.get('X-Forwarded-For') || request.headers.get('Remote-Addr');
    if (remoteIp) verifyFormData.append('remoteip', remoteIp);

    const url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'

    const result = await fetch(url, {
        body: verifyFormData,
        method: 'POST'
    })

    const outcome = await result.json();

    // 原有验证逻辑...
}

内容的提问来源于stack exchange，提问作者Chirdeep Tomar