企业官网建设流程全解析

前后端分离项目里，登录总是莫名其妙就掉了？Cookie明明写进去了，下一个请求又提示未认证？我在一个Spring Boot + Shiro的模拟项目X里排查这个问题，前后折腾了快两天，最后发现居然是SameSite这个属性在作怪。这篇就把排查思路、原理和最终落地的几种方案一次性说清楚，正好给正被这个坑绊住的朋友一个参考。

1. 先搞清楚SameSite到底挡了什么

1.1 一件小事引发的“跨站”惨案

事情是这样开始的。项目用的是Spring Boot 2.x + Shiro做登录认证和权限控制，部署之后本机测试一切正常，但只要一放到测试环境，或者从前端页面跨域调用接口，就会出现“已登录状态保存不住”的现象：登录接口明明返回了成功，紧接着的下一个业务请求就被Shiro拦截器踢回登录页，返回码直接给你一个401或者302。

最玄学的是，同一个环境，同事的Chrome能正常登录，我的Chrome就死活不行。刚开始怀疑是session超时配置问题，又怀疑是Redis session共享没配好，折腾了一圈，最后在浏览器DevTools的Network面板里看到响应头写着的Set-Cookie才恍然大悟。

那个Cookie长这样：

Set-Cookie: JSESSIONID=xxxxx; Path=/; HttpOnly; SameSite=Lax

如果放在几年前，这个Cookie根本没有SameSite这个字段。现在Chrome默认行为改了，只要你没显式指定，它就会按Lax处理。很多老项目升级浏览器之后突然出现登录失效、接口会话丢失，基本都是这个原因。

1.2 用门禁卡理解SameSite的三种模式

SameSite这个东西，我用一句大白话解释：它是浏览器对Cookie在“跨站”请求场景下的通行证策略。它管的是“我在A网站拿到的Cookie，到了B网站的请求里能不能带上”。

它有三个值：

那问题就来了：Chrome从80版本开始，把默认值从None改成了Lax。以前Cookie默认是跨站也能带，大家没感觉，现在浏览器帮你默认加了限制，跨站场景下Cookie自然就被扣下了。

Shiro默认把session id写在Cookie里，叫JSESSIONID。一旦这个Cookie在跨站请求时被浏览器扣下，后端一看请求里没有session id，就会认为当前用户没有登录，于是——登录失效、无限跳登录页、接口报未授权，全来了。

注意：这里说的“跨站”，不一定是跨域名。主域名相同但端口不同、子域不同、或者你用IP访问而前端页面用的是域名，这些情况在某些浏览器策略下也可能被判定为跨站。这正是很多人本地测得好好的、上测试环境就翻车的核心原因。

2. Shiro的Cookie写入逻辑与踩坑点

2.1 Shiro的SessionID Cookie是怎么回事

Shiro做认证的核心机制是：用户登录成功后，Shiro创建一个Session，然后把Session的ID写到Cookie里，下次请求再通过Cookie里的Session ID找回Session，从而判断用户是否已登录。

Spring Boot项目里，Shiro默认的Cookie Key是JSESSIONID。这个Cookie通常由Shiro自己生成并写入响应头。写Cookie的代码在Shiro的CookieConfig里，你可以用它来配置Cookie的大小写、域名、路径、过期时间等属性。

@Bean public CookieConfig cookieConfig() { CookieConfig cookieConfig = new CookieConfig(); cookieConfig.setName("JSESSIONID"); cookieConfig.setPath("/"); cookieConfig.setHttpOnly(true); cookieConfig.setMaxAge(-1); return cookieConfig; }

以上配置只管了名字、路径、HttpOnly这些基本项，完全没有提到SameSite。以前浏览器默认不添加SameSite属性，所以一切相安无事。但Chrome 80之后，浏览器开始“替你做主”，默认按照Lax处理，这才是问题爆发的起点。

2.2 哪些场景最容易踩雷

不是所有Shiro项目都会踩到SameSite问题，触发概率最高的场景有三个：

场景一：前后端完全分离部署。

前端站点和后端接口不在同一个域名下，比如前端是https://app.example.com，后端是https://api.example.com，前端调接口时跨站了，Cookie带不上去，用户登录状态就是摆设。

场景二：从页面A跳转到页面B，再调后端接口。

比如用户从某一个门户站点单点登录跳到业务系统，如果这两个站点的域名不同，业务系统种下的Cookie在用户跳回来之后再次请求时，有可能被浏览器拦下。

场景三：生产和本地环境之间的差异。

本地开发时，前端是localhost:8080，后端是localhost:9090，浏览器对localhost有特殊容忍，很多策略不生效；但生产环境换成了域名加HTTPS，各种限制都来了，这就是为什么本地跑得好好的，一到服务器就掉链子。

我自己那次遇到的场景比这些还要隐蔽——前端和后端同一域名，但是前端静态页面走了CDN，API请求直接打到源站，因为源站IP和域名之间的“站”判定不一致，结果也触发了跨站限制，愣是查了半天。

2.3 别被Shiro版本误导

排查过程中我翻了很多帖子，有人说“改Shiro的CookieConfig加一个setSameSite("None")就行”。确实，Shiro从1.7.1版本开始，在CookieConfig和SimpleCookie里提供了setSameSite方法。但如果你项目里用的还是老版本，比如1.4.x或1.5.x，这个方法根本不存在，强行调用会直接编译报错。

这就引出了第一个排查关键点：先确认项目里的Shiro版本。

<dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-spring-boot-starter</artifactId> <version>1.8.0</version> </dependency>

用1.7.1及以上版本，改配置就能解决；用老版本，就得走后面的手工方案。

但版本只是第一步，更大的坑还在后面：改了SameSite=None，Cookie还是不生效，这是为什么？下面进到实操环节，逐一把方案讲透。

3. 终结方案：四种改法逐个拆解

3.1 方案一：升级Shiro并配置SameSite

这是最正统、最省事的方案，适合Shiro 1.7.1以上的项目。

升级依赖之后，在ShiroConfig里把CookieConfig的SameSite属性设为None：

@Bean public CookieConfig cookieConfig() { CookieConfig cookieConfig = new CookieConfig(); cookieConfig.setName("JSESSIONID"); cookieConfig.setPath("/"); cookieConfig.setHttpOnly(true); cookieConfig.setMaxAge(-1); cookieConfig.setSameSite("None"); return cookieConfig; }

注意：你还需要把ShiroConfig里其他和Cookie相关的Bean也一并检查。很多时候项目里有多个CookieConfig实例，你只改了一个，另外一个默认配置照样把SameSite覆盖回去。

检查方式简单粗暴：登录成功后，打开浏览器DevTools，清掉Cookie，重新登录，看响应头里的Set-Cookie到底长什么样。如果依然是SameSite=Lax，说明你改的那个Bean根本没生效。

这套方案的优点是完全从源头解决，符合Shiro自己的设计，后续升级版本也不会出问题。缺点是要求Shiro版本足够新，如果项目里锁定老版本改不了，看下一种方案。

3.2 方案二：登录成功后的手工Cookie覆盖

我在查资料和反复试验的过程中，最终在一个模拟项目X里稳定用的是这个方案。核心思路是：不管Shiro怎么生成Cookie，登录成功后我们自己再往响应里塞一个正确的Cookie。

具体做法是，在登录接口的Controller里，登录认证成功之后，通过HttpServletResponse手动添加一个Set-Cookie头：

@PostMapping("/login") public ResultVO login(@RequestBody LoginVO loginVO, HttpServletResponse response) { // 先执行Shiro登录逻辑，保证Subject已经登录 Subject subject = SecurityUtils.getSubject(); try { subject.login(new UsernamePasswordToken(loginVO.getUsername(), loginVO.getPassword())); } catch (AuthenticationException e) { return ResultVO.error("用户名或密码错误"); } // 拿到Shiro刚写的session id String sessionId = (String) subject.getSession().getId(); // 生成一个手动构造的Cookie StringBuilder sb = new StringBuilder(); sb.append("JSESSIONID=").append(sessionId) .append("; Path=/") .append("; HttpOnly") .append("; SameSite=None") .append("; Secure"); response.setHeader(HttpHeaders.SET_COOKIE, sb.toString()); return ResultVO.success(); }

这套方案的原理是：Shiro的默认写Cookie动作发生在拦截器链内部，登录接口执行完subject.login之后，Shiro会把Cookie写入当前响应。之后我们再把响应头里的Set-Cookie整体覆盖掉，替换成带SameSite=None和Secure的新Cookie。浏览器收到响应时，以最后的Set-Cookie头为准。

注意：只要SameSite的值是None，浏览器就强制要求Cookie必须带有Secure属性。Secure意味着这个Cookie只允许通过HTTPS发送。如果你的测试环境是HTTP，那整个Cookie会被浏览器直接拒绝，登录状态照样保不住。这个限制是硬性的，绕不过，除非你退回Lax方案或者只做HTTPS。

如果生产环境是HTTPS，这套方案非常好用，升级都不用，直接改登录接口就行。

3.3 方案三：在Nginx层统一改写Cookie

如果项目前面挂了Nginx，而且你不想动Java代码，还有一条野路子：在Nginx配置里给Set-Cookie响应头追加SameSite属性。

Nginx里可以用proxy_set_header处理请求头，但响应头需要借助headers-more模块或sub_filter来处理。用sub_filter的方式比较简单粗暴：

location /api/ { proxy_pass http://backend-server; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; sub_filter_once off; sub_filter 'Set-Cookie: JSESSIONID=' 'Set-Cookie: JSESSIONID=; SameSite=None; Secure'; }

但这个方法有一个比较烦人的点：Nginx的sub_filter只能替换响应体里的内容，对响应头的改写能力有限。真正要在响应头里加Set-Cookie属性，需要用more_set_headers，而这个命令可以追加，但对现有Cookie进行部分修改比较吃力。

所以这个方案更常见的操作是后端先不写SameSite，Nginx在返回给浏览器之前给Set-Cookie后面统一添加：

location / { proxy_pass http://backend-server; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; header_filter_by_lua_block { local h = ngx.header['Set-Cookie'] if h ~= nil then ngx.header['Set-Cookie'] = h .. '; SameSite=None; Secure' end } }

这段脚本用的是OpenResty的Lua模块能力。如果公司生产环境是标准Nginx，没有装相关模块，这个方法没法直接用。所以在选这个方案前，先确认清楚Nginx支持哪些模块，别写到一半发现环境不支持。

我把这个方案放在第三位，就是因为它对基础设施的依赖比较重，适合容器化或网关层统一的公司，对业务代码零侵入，改一次能管几百个服务。但对一个中台项目来说，未必值得为这一个Cookie问题去动Nginx配置。

3.4 方案四：通用Filter兜底方案

有没有一个不依赖Shiro版本、不改登录接口、不碰Nginx、还对所有Java服务都生效的方案？有，自己写一个Filter。

思路是：用过滤器拦截所有请求，在响应返回前统一检查Set-Cookie头，如果发现Cookie里没有SameSite属性，就自动追加。这样你后面换框架、换认证方式，都不用再改。

@Component public class SameSiteFilter implements Filter { @Override public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException { HttpServletResponse response = (HttpServletResponse) servletResponse; // 包装响应对象，拦截Set-Cookie头 HttpServletResponseWrapper responseWrapper = new HttpServletResponseWrapper(response) { @Override public void setHeader(String name, String value) { if (name.equalsIgnoreCase("Set-Cookie") && !value.toLowerCase().contains("samesite")) { value = value + "; SameSite=None; Secure"; } super.setHeader(name, value); } @Override public void addHeader(String name, String value) { if (name.equalsIgnoreCase("Set-Cookie") && !value.toLowerCase().contains("samesite")) { value = value + "; SameSite=None; Secure"; } super.addHeader(name, value); } }; filterChain.doFilter(servletRequest, responseWrapper); } }

写完Filter之后，在启动类上不用特殊处理，只要这个类能被Spring Boot扫到，它就会自动对所有请求生效。

但这个方案有个细节必须注意：Filter的注册顺序。如果这个Filter在Shiro的Filter前面执行，它就能包装到Shiro写入的Cookie；如果执行顺序反了，等Shiro写完Cookie之后这个过滤器才执行，它也能通过responseWrapper拦截到——Spring的Filter链是按注册顺序执行的，只要这个Filter的注册顺序在Servlet容器写入响应头之前就行，实际测试中放在Shiro Filter后面也可以，因为HandlerInterceptor的执行和后来过滤器对响应头的修改，顺序上能覆盖到。

更保险的做法是给Filter标注@WebFilter(urlPatterns = "/*", filterName = "sameSiteFilter")，配合启动类的@ServletComponentScan扫描，指定early加载，确保它在最前面。

这是一个“一劳永逸”的兜底方案，但是在正式环境里，我建议用之前先问一个问题：你确认项目里所有Set-Cookie都是需要跨站的？如果有些Cookie涉及敏感安全区，你直接统一改成SameSite=None + Secure，等于把安全门槛降低了，这个权衡需要想清楚。

3.5 方案对比：怎么选最合适的

我把四种方案放在一起做了个对比，方便你直接对号入座：

我个人在实际项目里用下来，单服务Small项目推荐方案二；多服务而且Shiro版本旧，推荐方案四；版本新，直接方案一就行。

4. 排障实录：那些一度让我怀疑人生的怪现象

4.1 改成了SameSite=None为什么还是不行

这个坑是最常见的。很多人在代码里配置了SameSite=None，打开DevTools却发现Cookie根本没写入浏览器。排查到最后就一个原因：缺了Secure属性。

我之前说过，浏览器规定：SameSite=None必须配合Secure属性一起使用。Secure要求请求必须走HTTPS。如果你用的是http://localhost:8080或http://192.168.x.x，Cookie会被浏览器直接拒绝。这种情况下的表现是：登录接口200返回，但Cookie那一行看不到任何Set-Cookie，或者在Application面板里找不到Cookie。

解决办法是：要么给测试环境配HTTPS证书，要么暂时把SameSite改成Lax。相比之下，开发环境先配一个自签名证书比跟浏览器死磕要省事得多。

为了验证是不是Secure捣的鬼，我教大家一个快速判别法：在浏览器DevTools的Network面板里看登录请求的响应头，如果Set-Cookie是灰的或者被浏览器标记为“此Cookie因被设置为Secure且请求未使用HTTPS而被拒绝”，那基本就是这个问题。这时候哪怕是SameSite=Lax，也照样没有Cookie，因为Lax虽然没有强制Secure，但是Lax在跨站时根本不会带，还是要用HTTPS。

4.2 多个Set-Cookie头互相覆盖

登录接口返回的响应头里，可能出现两个Set-Cookie头。一个是Shiro写的，另一个是框架或业务代码补的。浏览器对于同名Cookie的处理原则是：后写的覆盖先写的。如果你的代码在后面补了一个不带SameSite的Cookie，那之前的SameSite=None就白配了。

我之前用方案二的时候，就出现过这种情况：手动加的Cookie明明带了SameSite=None，但浏览器里看到的还是老版本Cookie，原因就是响应头里有两个Set-Cookie，我手动加的在前面，某个框架隐式补的在后面，后者把前者覆盖了。

实战提示：遇到这种问题，先清空浏览器所有Cookie，再重新登录，看响应头里到底有几个Set-Cookie。如果发现自己没法控制多个Cookie写入的顺序，可以在Filter里把现有的Set-Cookie全部截获、拼接到一个Set-Cookie头里再写回去，这样就不会出现同名覆盖的问题。

4.3 明明没跨域，为什么还触发跨站限制

另一个容易让人抓狂的场景：前端和后端同域名、同端口，按理说不存在跨站问题，结果Chrome还是把Cookie拦了。

这个情况我后来仔细查了一下，主要出在IP和域名混用上。比如你页面是用http://localhost:8080访问的，但接口地址写的是http://127.0.0.1:8080，这在浏览器的“站”判定逻辑里，localhost和127.0.0.1属于不同的site。同理，用机器名访问和用IP访问，也可能被判定成跨站。

解决办法是：前端页面和后端接口的访问方式保持绝对一致。要么都用域名，要么都用IP，不要混搭。前端域名是http://test.example.com，后端接口也必须是http://test.example.com/api/xxx，少一个也不行。

这种问题表面上看着是SameSite问题，其实是因为“站”的判定参数没对齐。建议在配置代理时，把前端的host头始终透传给后端，前端页面和后端接口用同一个host去访问，能少踩很多坑。

4.4 老版本Shiro没有setSameSite方法，如何曲线救国

如果项目锁死了Shiro老版本，不能升级，也没有条件做Filter或者Nginx改造，还有最后一个备用手段：在Java代码里用反射调用SimpleCookie设置SameSite。

为什么用反射？因为老版本的CookieConfig里没有setSameSite方法，但底层的SimpleCookie在某些版本里已经预留了私有字段，只是没暴露公共方法。你可以通过反射硬塞一个值进去。这段代码虽然看起来丑，但在极端场景下确实能解燃眉之急：

@Bean public CookieConfig cookieConfig(SecurityManager securityManager) { CookieConfig cookieConfig = new CookieConfig(); cookieConfig.setName("JSESSIONID"); try { Field sameSiteField = cookieConfig.getClass().getDeclaredField("sameSite"); sameSiteField.setAccessible(true); sameSiteField.set(cookieConfig, "None"); } catch (Exception e) { // 反射失败时不影响正常启动，但不保证SameSite属性会被写入 } return cookieConfig; }

需要注意的是，反射方案依赖于具体版本里的字段名字，换一个版本可能字段名就变了，所以它最适合作为临时方案，后续还是得规划升级路径。

5. 在实际项目中踩出来的几条重要心得

5.1 不要只盯着后端代码

SameSite问题的表象是Cookie不生效、session丢失，但根源往往散落在前端配置、Nginx代理、浏览器策略、部署方式等多个环节。后端代码只是其中一个变量。排查顺序应该是：先打开浏览器看真实请求和响应，确认Cookie的完整内容；再判断是“没写Cookie”还是“写了但被浏览器拒收”；最后再动手改代码。

我在第二个项目中遇到过类似情况，登录接口返回的Set-Cookie一切正常，SameSite=None和Secure都在，但用户的Cookie就是写不进去，后来发现是前端的Axios请求把withCredentials给关了。浏览器策略允许携带，前端自己不给带，照样白搭。所以前端也要同步确认：跨域请求时是否设置了withCredentials: true，如果用了代理，代理配置是否正确透传了Cookie头。

5.2 长期方案，尽量统一到HTTPS

SameSite问题最根本的解法，其实是把服务统一切到HTTPS。HTTPS加上SameSite=None+Secure，既保证跨站场景的可用性，又不牺牲安全属性。只要全站都是HTTPS，就不存在Secure导致Cookie被拒的问题，SameSite=None也成了合法配置。

如果项目短期无法全站HTTPS，只能做兼容：Lax模式下的跨站场景受限，你得评估业务模型是否允许。有些后台系统的业务形态就是单一站点，Cookie不需要跨站，甚至不应该跨站，那么保留Lax反而更安全，没必要硬改成None。

5.3 排查工具的正确打开方式

DevTools里的Application面板能看到最终的Cookie存储状态，Network面板能看到请求和响应头，这两个结合起来，基本能覆盖90%的排查场景。推荐的做法是：先在Network里看登录请求，确认Set-Cookie响应头里的完整Cookie值；再到Application里看当前域名下的Cookie列表，确认Cookie是否真的被保存下来；最后切换页面、重新发请求，看Request Headers里有没有带上这个Cookie。

整个过程就是三段式：种Cookie、存Cookie、带Cookie。哪一步断了，问题就在哪一步。不用一上来就怀疑Shiro配置、怀疑内存泄漏、怀疑Session共享方案，先走完这三步再说。

顺着这个思路，我还补过一个排查技巧：在Chrome地址栏输入chrome://flags，把SameSite by default cookies相关的实验开关关掉再测试，能快速验证是不是被默认策略坑了。这个方法不适合给用户推荐，只是开发环境临时验证用的。

6. 最后分享一个最省心的小技巧

如果公司内部是标准容器化部署，团队里的人都要被这个问题折腾一遍，建议直接用一个统一的基础镜像或在公共组件库里放一个上文提到的SameSiteFilter，新服务接进来默认带这个Filter。这样既不用每个人排查半天，也不会出现A服务改了、B服务遗漏的情况。

回看这个问题的全过程，表面上是一个浏览器策略变更引发的登录状态丢失，实际上牵涉到框架版本、跨站判定、HTTPS部署、前端请求配置等多个环节。身边还有不少人在用老版本Shiro，升级一时半会儿提不上日程，那方案二和方案四值得优先试。至少我后来在一堆老项目里，就是靠一个Filter加一套登录接口覆盖，把问题稳稳收住的。