用途：指导在静态优先的 Astro 项目中，通过 React 岛集成 CometChat（@cometchat/chat-uikit-react@^6，配合 @cometchat/calls-sdk-javascript@^5），实现会话列表、消息列表、消息输入等聊天界面。
主要能力与要点： 1）项目检测：package.json 含 astro 依赖即视为 Astro 项目；若缺少 @astrojs/react，需先执行 npx astro add react，并确认 astro.config.mjs 的 integrations 数组包含 react()。 2）关键规则：所有渲染 CometChat 的 Astro 组件必须使用 client:only="react"；client:load、client:visible、client:idle 会先服务端渲染并因访问 window 而报错，无指令则无法交互。 3）Provider：使用 React 组件形式，在 React 岛内部挂载，而非 Astro 布局层。CSS（@cometchat/chat-uikit-react/css-variables.css）必须在 React 组件文件内导入，因为 client:only 岛与 Astro 的 CSS 管线隔离。模块级 initialized 与 loginInFlight 变量用于防止 React StrictMode 重复初始化与重复登录。 4）页面与组件：可用 CometChatConversations、CometChatMessageHeader、CometChatMessageList、CometChatMessageComposer 组合出会话+聊天布局；抽屉/弹窗组件的触发按钮也必须位于同一 React 岛内。 5）岛间通信：不同 React 岛不共享 state/context/ref，可用自定义 DOM 事件、nanostores（npm install nanostores @nanostores/react）或 URL 查询参数。 6）环境变量：客户端变量需 PUBLIC_ 前缀（如 PUBLIC_COMETCHAT_APP_ID、PUBLIC_COMETCHAT_REGION、PUBLIC_COMETCHAT_AUTH_KEY），经 import.meta.env 访问；服务端变量无前缀，可在 API 路由中使用。.env 默认不被 gitignore，建议手动加入。
限制：示例中的登录 UID 仅用于开发，生产认证方案未在本资料中给出；API 路由需按所用 Astro 版本配置按需渲染（Astro 3 设置 output: "server" 或 "hybrid"，Astro 4+ 按路由选择加入），具体细节资料中未完整提供；使用前应核对已安装包中的符号。