前台表单与 AJAX 的 CSRF 令牌
校对日期:2026-11-16。适用于社区版及全部商业版。
前台用会话(Cookie)识别登录的会员,所以凡是修改数据的请求都要带上 CSRF 令牌,防止第三方网站借访客的登录状态提交数据。 本文面向主题开发者,说明哪些请求要带令牌、令牌从哪里取、表单和 AJAX 各怎么带,以及静态页和被缓存的页面要注意什么。 主题的整体写法见主题开发。
一、哪些请求需要令牌
| 请求 | 是否校验 | 说明 |
|---|---|---|
前台地址和 /frontend/** 接口的 POST、PUT、DELETE、PATCH | 校验 | 包括登录 POST /login、退出 POST /logout,以及模板里以 ${api} 开头的写接口 |
GET、HEAD、OPTIONS、TRACE | 不校验 | 读数据不用带令牌;修改数据的操作不要做成 GET |
/api/** | 不校验 | 这组接口不使用会话,凭请求头 Authorization: Bearer <访问令牌> 识别用户,前台的登录状态对它不生效 |
公开接口大多同时提供两个地址:/api/… 和 /frontend/…。模板变量 ${api} 指向后者(部署在子路径下时带该路径), 所以在主题里用 ${api} 调用接口时,访客的登录状态有效,写请求也就必须带令牌。小程序、App 等不经过前台页面的调用方使用 /api/…, 接口清单见文档站的“API 和标签”部分。
没带令牌或令牌不对,请求不会执行,返回 403。
二、令牌从哪里取
模板变量 _csrf。 动态渲染的页面里可以直接使用:
| 表达式 | 值 |
|---|---|
${_csrf.token} | 令牌 |
${_csrf. | 放在表单里时的字段名,为 _csrf |
${_csrf. | 放在请求头里时的名称,为 X-CSRF-TOKEN |
接口 GET ${api}/(即 /frontend/)。返回同样的三项,供脚本在提交前现取:
{"headerName":"X-CSRF-TOKEN","parameterName":"_csrf","token":"FCHrKBW7ePgK…"}令牌保存在访客的服务器端会话里,请求时要带上会话 Cookie;换了会话,原来的令牌就失效。
带令牌的方式有两种,任选其一:作为表单字段 _csrf 提交,或放在请求头 X-CSRF-TOKEN 里。
三、表单提交
在表单里加一个隐藏字段。默认主题的退出按钮(templates/)就是这样写的:
[#escape x as (x)!?html]
<form action="${ctx}/logout" method="post">
<button type="submit">退出</button>
<input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}">
</form>
[/#escape]登录表单(templates/)同理。这种写法把令牌直接写进了页面,只适合不会被缓存、也不会生成静态页的页面: 登录页、注册页、会员中心和 /app/<名称> 片段页都属于这一类。其它页面见“静态页与被缓存的页面”一节。
四、AJAX 提交
默认主题的做法分三步,自己的主题可以照搬:
在
<head>里输出令牌(snippets/):meta. html freemarker[#escape x as (x)!?html] <meta name="_csrf" content="${_csrf.token}"> <meta name="_csrf_header" content="${_csrf.headerName}"> [/#escape]提交前重新取一次令牌。
assets/提供js/ theme.js window.:请求fetchCsrf() ${api}/env/csrf,把结果写回上面两个<meta>,并返回{headerName, parameterName, token}。它依赖snippets/里的js. html window.。visitApi = '${api}' 把令牌放进请求头。
window.对request(method, url, body) GET、HEAD以外的请求自动从<meta>读出令牌并加到请求头, 请求体按 JSON 发送。
默认主题里所有写操作都是这两行,例如栏目页的“关注”按钮(templates/):
await window.fetchCsrf();
await window.request('POST', '${api}/follow', { channelId: '${channel.id?c}' });不使用这两个函数时,自己取令牌、自己加请求头即可:
<script nonce="${csp_nonce!''}">
async function post(url, body) {
const csrf = await fetch('${api}/env/csrf', { credentials: 'include' }).then(r => r.json());
return fetch(url, {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json', [csrf.headerName]: csrf.token },
body: JSON.stringify(body),
});
}
</script>上传文件等不是 JSON 的请求,同样把令牌放在请求头里,写法见默认主题的 templates/ 和 templates/。
五、静态页与被缓存的页面
页面里写好的令牌不一定还能用,所以默认主题每次提交前都调用 fetchCsrf(),而不是直接用页面里的值:
- 静态页。 生成静态页时没有访客会话,
_csrf是空的。默认主题的模板都包在[#escape x as (x)!?html]里,空值输出为空字符串,<meta>的内容留空,提交前由fetchCsrf()填上。没有用这种转义写法的模板要写成${(_,否则生成静态页会报错。csrf. token)!} - 浏览器缓存的页面。 未登录访问首页、栏目页、文章页等页面时,浏览器会把页面缓存 5 分钟(见前台页面缓存与 CDN), 缓存页面里的令牌可能属于已经结束的会话。
- 不要把令牌写进
.js文件或其它会被长期缓存、被多人共用的内容。 - 集群部署。 令牌在单个节点的会话里,负载均衡要开启会话保持,见集群部署的“会话保持与登录”一节。
/app/<名称> 片段页的响应不缓存,页面里的表单可以直接用隐藏字段。
六、常见问题
提交返回 403,提示 Invalid CSRF Token 'null' was found on the request parameter '_ 请求没有带令牌,或者带的令牌不属于当前会话(两种情况的提示相同)。在浏览器开发者工具的“网络”里查看这次请求:请求头里有没有 X-CSRF-TOKEN,或表单数据里有没有 _csrf。没有就补上;有却仍然报错,说明令牌是旧的,改为提交前调用 ${api}/env/csrf 现取。
提交返回 403,提示 Could not verify the provided CSRF token because no token was found to compare. 服务器上找不到这位访客的令牌:请求没有带会话 Cookie,或者会话已经失效。先带着 Cookie 请求一次 ${api}/env/csrf 再提交; 集群环境检查会话保持是否生效。
GET / 返回 404。/api/** 不使用会话,也没有令牌,那里没有这个接口。取令牌要用 /frontend/,在模板里写 ${api}/env/csrf 即可。