用途:为原生 Next.js 应用接入 ibl.ai SSO 认证,未认证用户会被重定向到 login.iblai.app,登录后带会话返回,无需管理 API 令牌。
前提条件:Next.js 14+ 且使用 App Router(app/ 目录);Node.js 18+;已安装 iblai CLI(可用 iblai --version 检查,未安装可运行 /vibe-install-cli);需要 ibl.ai 租户密钥(免费默认租户用 iblai,或在 https://iblai.app 注册)。
主要用法:在项目目录运行 iblai add auth(或 npx @iblai/cli add auth)。生成器会创建 7 个文件并修改 next.config、globals.css 和 .env.local,自动识别 src/ 目录布局。随后执行 pnpm install 安装依赖(@iblai/iblai-js、@reduxjs/toolkit、react-redux、sonner、lucide-react、react-markdown、remark-gfm)。在 app/layout.tsx 中用生成的 IblaiProviders 包裹 {children},它必须是最外层 provider。编辑 .env.local 配置 API、认证、WebSocket 地址与租户密钥。确认 globals.css 含 SDK 样式导入。运行 pnpm dev 后访问 http://localhost:3000 应被重定向到登录页,登录后返回并可在 localStorage 看到 axd_token、userData、tenants。
生成内容:SSO 回调页、配置访问器、localStorage 封装、认证工具、Redux store、Provider 链、SDK 样式文件。
限制与注意:SSO 回调页不能被 AuthProvider 包裹,否则会重定向循环,生产环境建议用路由组将其隔离;@reduxjs/toolkit 需在 next.config.mjs 中做 webpack 别名去重,否则 SDK 组件会静默返回 undefined;localhost 上 custom-domains 报错可忽略;.env.local 必须设置 NEXT_PUBLIC_MAIN_TENANT_KEY,否则可能白屏。后续可继续添加 chat、profile、account、analytics、notifications 等功能。