9b90f589d5
- 更新widget/README.md中的文档链接 - 在cwd-comments-admin/index.html中添加favicon - 更新docs/.vitepress/config.mjs中的标题和favicon配置 - 在cwd-comments-admin/src/views/LayoutView.vue中添加文档链接 - 全面重写并完善API文档结构，包括overview.md、public.md和admin.md - 更新前端配置文档frontend-config.md和后端配置文档backend-config.md
217 lines
8.1 KiB
Markdown
217 lines
8.1 KiB
Markdown
# 前端配置
|
||
|
||
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。**
|
||
|
||
当前前端部分主要由两块组成：
|
||
|
||
- 评论组件（widget）：以 UMD 库形式输出 `cwd-comments.js`，可在任意站点中直接通过 `<script>` 引入。
|
||
- 管理后台（admin）：基于 Vite + Vue 3 的单页应用，用于管理评论和系统配置。
|
||
|
||
> 相关 API 文档见：[公开 API](../api/public.md) 和 [管理员 API](../api/admin.md)
|
||
|
||
## 环境与项目结构
|
||
|
||
前端目录结构与运行时环境：
|
||
|
||
- `widget/`：评论组件源码
|
||
- 运行环境：浏览器（支持现代浏览器）
|
||
- 构建工具：Vite
|
||
- `cwd-comments-admin/`：管理后台源码
|
||
- 运行环境：浏览器
|
||
- 构建工具：Vite + Vue 3
|
||
|
||
Node.js 版本建议使用 `>=18`，与后端保持一致即可。
|
||
|
||
### 环境变量与多环境配置
|
||
|
||
评论组件本身不依赖打包时的环境变量，只需要在运行时传入 `apiBaseUrl` 即可。
|
||
管理后台使用 Vite 环境变量进行多环境配置，推荐按以下方式区分开发 / 测试 / 生产环境：
|
||
|
||
在 `cwd-comments-admin` 目录下创建对应的环境文件：
|
||
|
||
```bash
|
||
# 开发环境
|
||
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）
|
||
|
||
开发和构建评论组件：
|
||
|
||
```bash
|
||
cd widget
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 本地开发预览
|
||
npm run dev
|
||
|
||
# 构建 UMD 库（生成 cwd-comments.js）
|
||
npm run build
|
||
```
|
||
|
||
构建完成后，将 `widget/dist/cwd-comments.js` 部署到你的静态资源服务器或 CDN，示例：
|
||
|
||
```html
|
||
<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）
|
||
|
||
管理后台用于审核评论、删除评论和管理评论设置。
|
||
|
||
```bash
|
||
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` 实例时，可以传入以下配置参数：
|
||
|
||
```html
|
||
<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 地址即可，无需额外前端跨域配置，例如：
|
||
|
||
```javascript
|
||
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 的更详细说明见：[后端配置](./backend-config.md#跨域配置与安全性)。
|
||
|
||
## 静态资源部署规范
|
||
|
||
为了保证前端资源加载稳定，建议按如下规范部署静态资源：
|
||
|
||
- 使用 HTTPS 域名托管 `cwd-comments.js` 以及管理后台构建产物。
|
||
- 将评论组件脚本放在具备缓存能力的静态资源域名或 CDN 上，例如：
|
||
- `https://static.example.com/cwd-comments/v0.0.1/cwd-comments.js`
|
||
- 当发布新版本时，建议通过路径或文件名中的版本号进行区分，避免缓存错乱。
|
||
- 页面中引入脚本时保持路径稳定，便于后续版本升级：
|
||
|
||
```html
|
||
<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()` | 获取当前配置 |
|
||
|
||
## 使用示例
|
||
|
||
```javascript
|
||
// 动态切换主题
|
||
comments.updateConfig({ theme: 'dark' });
|
||
|
||
// 切换文章
|
||
comments.updateConfig({ postSlug: 'another-post' });
|
||
```
|