cwd/docs/guide/frontend-config.md

前端配置

这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。

当前前端部分主要由两块组成：

• 评论组件（widget）：以 UMD 库形式输出 cwd-comments.js，可在任意站点中直接通过 <script> 引入。
• 管理后台（admin）：基于 Vite + Vue 3 的单页应用，用于管理评论和系统配置。

相关 API 文档见：公开 API 和 管理员 API

环境与项目结构

前端目录结构与运行时环境：

• widget/：评论组件源码
  • 运行环境：浏览器（支持现代浏览器）
  • 构建工具：Vite
• cwd-comments-admin/：管理后台源码
  • 运行环境：浏览器
  • 构建工具：Vite + Vue 3

Node.js 版本建议使用 >=18，与后端保持一致即可。

环境变量与多环境配置

评论组件本身不依赖打包时的环境变量，只需要在运行时传入 apiBaseUrl 即可。
管理后台使用 Vite 环境变量进行多环境配置，推荐按以下方式区分开发 / 测试 / 生产环境：

在 cwd-comments-admin 目录下创建对应的环境文件：

# 开发环境
cp .env.example .env.development

# 测试环境
cp .env.example .env.test

# 生产环境
cp .env.example .env.production

每个环境文件中可配置以下变量：

变量名	说明	示例
VITE_API_BASE_URL	后端 API 地址（Cloudflare Worker 域名或自定义）	https://cwd-comments-api.test.com
VITE_ADMIN_NAME	登录页默认管理员账号占位值	admin@example.com
VITE_ADMIN_PASSWORD	登录页默认密码占位值	123456

说明：

• VITE_API_BASE_URL 会作为管理后台的默认 API 地址，实际请求地址可以在登录页修改，并持久化到 localStorage。
• VITE_ADMIN_NAME 和 VITE_ADMIN_PASSWORD 仅用于自动填充登录表单，真正的认证信息以后端环境变量 ADMIN_NAME、ADMIN_PASSWORD 为准。

依赖安装与启动流程

评论组件（widget）

开发和构建评论组件：

cd widget

# 安装依赖
npm install

# 本地开发预览
npm run dev

# 构建 UMD 库（生成 cwd-comments.js）
npm run build

构建完成后，将 widget/dist/cwd-comments.js 部署到你的静态资源服务器或 CDN，示例：

<script src="https://static.example.com/cwd-comments/cwd-comments.js"></script>
<div id="comments"></div>
<script>
  const comments = new CWDComments({
    el: '#comments',
    apiBaseUrl: 'https://your-api.example.com',
    postSlug: 'https://example.com/my-post'
  });
  comments.mount();
</script>

管理后台（cwd-comments-admin）

管理后台用于审核评论、删除评论和管理评论设置。

cd cwd-comments-admin

# 安装依赖
npm install

# 开发环境启动（默认端口见 vite.config.ts，一般为 1226）
npm run dev

# 生产环境构建
npm run build

# 本地预览生产构建结果
npm run preview

将 cwd-comments-admin/dist 目录部署到任意静态站点托管服务（如 Cloudflare Pages、Vercel、Netlify 等），并确保浏览器可以访问到后端 API 地址。

评论组件初始化

在初始化 CWDComments 实例时，可以传入以下配置参数：

<script src="https://cwd-comments.zishu.me/cwd-comments.js"></script>
<div id="comments"></div>
<script>
  const comments = new CWDComments({
    el: '#comments',
    apiBaseUrl: 'https://your-api.example.com',
    postSlug: 'https://example.com/my-post'
  });
  comments.mount();
</script>

参数说明

参数	类型	必填	默认值	说明
el	string | HTMLElement	是	-	挂载元素选择器或 DOM 元素
apiBaseUrl	string	是	-	API 基础地址
postSlug	string	是	-	文章唯一标识符
postTitle	string	否	页面标题或 postSlug	文章标题，用于邮件通知
postUrl	string	否	当前页面 URL	文章 URL，用于邮件通知
theme	'light' | 'dark'	否	'light'	主题模式
pageSize	number	否	20	每页显示评论数
avatarPrefix	string	否	https://gravatar.com/avatar	头像服务前缀
adminEmail	string	否	-	博主邮箱，用于显示博主标识
adminBadge	string	否	博主	博主标识文字

跨域访问配置

前端评论组件与管理后台均通过 HTTP 与后端交互。当前后端在 /api/* 和 /admin/* 路径下统一开启了 CORS：

• Access-Control-Allow-Origin: *
• 允许方法：GET, POST, PUT, DELETE, OPTIONS
• 允许请求头：Content-Type, Authorization
• 不允许携带 Cookie 等凭证（Access-Control-Allow-Credentials: false）

因此在常见部署方式下，你只需要在前端将 apiBaseUrl 指向后端 Worker 地址即可，无需额外前端跨域配置，例如：

const comments = new CWDComments({
  el: '#comments',
  apiBaseUrl: 'https://cwd-comments-api.example.com',
  postSlug: window.location.pathname
});
comments.mount();

如果你在本地同时运行前端和后端，可以按以下方式联调：

• 使用 wrangler dev 启动后端（默认端口一般为 8787，如有需要可使用 wrangler dev --port 8788 指定端口）。
• 在评论组件开发页面（widget/index.html）中，将 API 地址设置为对应本地端口，例如 http://localhost:8787。

后端关于 CORS 的更详细说明见：后端配置。

静态资源部署规范

为了保证前端资源加载稳定，建议按如下规范部署静态资源：

• 使用 HTTPS 域名托管 cwd-comments.js 以及管理后台构建产物。
• 将评论组件脚本放在具备缓存能力的静态资源域名或 CDN 上，例如：
  • https://static.example.com/cwd-comments/v0.0.1/cwd-comments.js
• 当发布新版本时，建议通过路径或文件名中的版本号进行区分，避免缓存错乱。
• 页面中引入脚本时保持路径稳定，便于后续版本升级：

<script src="https://static.example.com/cwd-comments/v0.0.1/cwd-comments.js"></script>

管理后台的构建结果同样建议部署到独立的静态站点域名下，例如：

• https://comments-admin.example.com 部署 cwd-comments-admin/dist

头像服务前缀

常用的 Gravatar 镜像服务：

服务	前缀地址
Gravatar 官方	https://gravatar.com/avatar
Cravatar (国内)	https://cravatar.cn/avatar
自定义镜像	https://your-mirror.com/avatar

实例方法

方法	说明
mount()	挂载组件到 DOM
unmount()	卸载组件
updateConfig(config)	更新配置（支持动态切换主题等）
getConfig()	获取当前配置

使用示例

// 动态切换主题
comments.updateConfig({ theme: 'dark' });

// 切换文章
comments.updateConfig({ postSlug: 'another-post' });