飞书二维码本地开发加载失败问题排查指南
📌 问题背景
在本地开发过程中，访问 http://192.168.x.x:port/auth/qrcode-login 时，飞书二维码组件无法正常加载，而 http://localhost:port/auth/qrcode-login 下二维码加载正常。
控制台报出如下警告：
Chrome is moving towards a new experience that allows users to choose to browse without third-party cookies.🧠 问题根因
飞书扫码登录依赖于 第三方 Cookie 以及 跨域资源加载，而现代浏览器（如 Chrome）对第三方 Cookie 存取有严格限制。
🚫 为什么 192.168.x.x 不行？
Chrome 认为 192.168.x.x 是不安全的上下文（非 secure origin），在该上下文中：
- Cookie 的
SameSite=None不会生效； - 第三方资源（如飞书二维码 SDK）尝试设置 Cookie 会被浏览器拦截；
- 导致二维码 SDK 登录流程被中断或二维码不显示。
✅ 为什么 localhost 可以？
localhost被视为浏览器的安全上下文（Secure Context）；- 即便是
http://localhost，也可以使用第三方 Cookie； - 飞书二维码加载与扫码登录流程均能正常完成。
✅ 推荐解决方案
方案一：使用 localhost 或 127.0.0.1 进行开发调试 ✅ 推荐
- 请将本地服务绑定在
localhost，而非192.168.x.x； - 示例访问地址应为：
http://localhost:5567/auth/qrcode-login💡 建议：如需远程设备访问本地服务，推荐使用
ngrok、localtunnel或frp将服务暴露为公网 HTTPS 域名。
方案二：搭建 HTTPS + 自签名证书（进阶）
如必须使用内网 IP 地址（如 192.168.x.x）：
- 为本地开发环境配置 HTTPS；
- 使用自签名证书，并在浏览器中信任；
- 确保请求头中允许
SameSite=None; Secure的 cookie； - 修改浏览器安全策略接受自签名 HTTPS。
⚠️ 本方案实现复杂，建议只用于企业内测或对接 QA 测试使用。
方案三：临时关闭浏览器 SameSite 策略（开发环境调试）
可在启动 Chrome 时添加启动参数，临时禁用 SameSite Cookie 策略：
macOS/Linux
bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--disable-features=SameSiteByDefaultCookies,CookiesWithoutSameSiteMustBeSecureWindows
bash
chrome.exe --disable-features=SameSiteByDefaultCookies,CookiesWithoutSameSiteMustBeSecure⚠️ 仅用于开发阶段调试，切勿在生产环境使用！
🔍 控制台 Warning 说明
Chrome is moving towards a new experience that allows users to choose to browse without third-party cookies.这是 Chrome 在为即将全面禁用第三方 Cookie 做预警。未来建议全面采用：
- 自定义 OAuth 网关；
- 使用一体化登录页统一跳转；
- 避免第三方 Cookie 的依赖。
✅ 总结建议
| 场景 | 推荐做法 |
|---|---|
| 本地调试 | 使用 localhost 而非 IP |
| 二维码无法加载 | 检查 Cookie 策略与浏览器上下文 |
| 跨设备调试 | 使用 ngrok/frp 提供 HTTPS 访问 |
| 企业内测 | 可搭建 HTTPS 内网服务 + 信任证书 |
📌 附：二维码 SDK 示例引用
html
<script src="https://lf-package-cn.feishucdn.com/obj/feishu-static/lark/passport/qrcode/LarkSSOSDKWebQRCode-1.0.111.js?v=1"></script>