CWD 评论系统集成指南
我已成功初始化 Astro 项目并集成了 CWD 评论系统。
主要变更
- 项目初始化: 使用
basics模板创建了新的 Astro 项目。 - 创建组件: 创建了可复用的 Astro 组件 [src/components/CwdComments.astro]。
---interface Props { apiBaseUrl: string; elId?: string; pageSize?: number; theme?: 'light' | 'dark';}const { apiBaseUrl, elId = 'comments', pageSize = 20, theme = 'light' } = Astro.props;---
<!-- 1. 容器:使用 data 属性传递参数给脚本 --><div id={elId} class="cwd-comments-container" data-el-id={elId} data-api-base-url={apiBaseUrl} data-page-size={pageSize} data-theme={theme}></div><!-- 2. 引入库文件:保持 is:inline 以便在任何时候都能加载 --><script is:inline src="https://unpkg.com/cwd-widget@latest/dist/cwd.js"></script><!-- 3. 初始化脚本:使用 module 引入你的工具函数 --><script> import { registerPageInit } from '@/utils/page-init'; // 定义初始化逻辑 const initComments = () => { const containers = document.querySelectorAll('.cwd-comments-container');
containers.forEach((container) => { const el = container as HTMLElement; // 防止重复初始化 (如果容器里已经有内容了 或 已经标记初始化) if (el.children.length > 0 || el.dataset.cwdInitialized) return; const apiBaseUrl = el.dataset.apiBaseUrl; const theme = el.dataset.theme; const pageSize = Number(el.dataset.pageSize);
// 检查库是否加载完成 if ((window as any).CWDComments && apiBaseUrl) { try { const comments = new (window as any).CWDComments({ el: el, apiBaseUrl, pageSize, theme, }); comments.mount(); // 标记已初始化 el.dataset.cwdInitialized = 'true'; } catch (e) { console.error('[CWD] Init failed:', e); } } else { // 如果脚本还在加载中,稍微轮询一下 const checkTimer = setInterval(() => { if ((window as any).CWDComments) { clearInterval(checkTimer); // 重新触发 initComments(); } }, 100); // 5秒后超时停止 setTimeout(() => clearInterval(checkTimer), 5000); } }); // 返回清理函数 (可选,如果库支持销毁) return () => { // CWD目前可能没有提供 destroy 方法,这里清空容器即可 // containers.forEach(el => el.innerHTML = ''); }; }; // 4. 注册到 PageInitManager // 使用一个唯一的名称 'init-cwd-comments' registerPageInit('init-cwd-comments', initComments, { immediate: true });</script>- 页面集成: 将评论组件添加到了主页 [src/pages/index.astro]。
如何配置
评论系统需要通过 API URL 连接后端。你需要更新 [src/pages/index.astro](或者其他使用该组件的地方)中的 apiBaseUrl 属性。
文件: [src/pages/index.astro]
<CwdComments apiBaseUrl="https://cmt-api.xxx.com" />请确保将 https://cmt-api.xxx.com 替换为你实际部署的 Worker URL。
组件使用方法
你可以在任何 Astro 页面或布局中使用 CwdComments 组件:
---import CwdComments from '../components/CwdComments.astro';---
<CwdComments apiBaseUrl="https://cmt-api.xxx.com" elId="comments" theme="light"/>验证
项目构建成功。你可以运行开发服务器查看评论组件(请确保 API URL 配置正确):
npm run dev在其他 Astro 项目中复用
要在其他 Astro 项目中使用此评论系统,无需重新部署后端或管理后台。只需复制前端组件即可。
-
复制组件: 将 [src/components/CwdComments.astro 复制到新项目的
src/components/目录。 注意:如果你的项目使用了 View Transitions,请确保保留组件内的registerPageInit逻辑。 -
添加到页面: 在页面中引入并使用:
---import CwdComments from '../components/CwdComments.astro';---<CwdComments apiBaseUrl="https://cmt-api.xxx.com" /> -
唯一标识: 系统会根据页面 URL (路径) 自动区分评论。只要新项目的域名或路径不同,评论就会自动隔离。
保持更新
由于 CWD 处于早期开发阶段,更新较频繁。请参考以下更新策略:
-
后端 (API):
- 在
cwd目录运行git fetch upstream和git merge upstream/main同步代码。 - 运行
npm install更新依赖。 - 运行
npx wrangler d1 migrations apply CWD_DB(如果有数据库变更)。 - 运行
npm run deploy部署新版本 Worker。
- 在
-
前端组件:
- 在
src/components/widgets/CwdComments.astro中更新脚本 URL 版本:<script is:inline src="https://unpkg.com/cwd-widget@latest/dist/cwd.js"></script> - 使用
@latest获取最新版(开发推荐),或指定版本号(如@0.0.5)以保证稳定性。
- 在
-
管理后台:
- 拉取最新代码 (同后端步骤)。
- 运行
npm install和npm run build。 - 重新部署到 Cloudflare Pages:
npx wrangler pages deploy dist --project-name cwd-admin。
发布于: 2026年2月6日 · 修改于: 2026年2月6日