From 1975e519607e27c128c246019984e5fc27a4fbee Mon Sep 17 00:00:00 2001 From: shumengya Date: Thu, 4 Jun 2026 22:03:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E4=BB=93=E5=BA=93?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=88README=20/=20LICENSE=20/=20CONTRIBUT?= =?UTF-8?q?ING=20/=20CHANGELOG=20/=20Issue=20=E4=B8=8E=20PR=20=E6=A8=A1?= =?UTF-8?q?=E6=9D=BF=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: 仓库门面，含特性、API 文档、快速开始、部署、目录结构、协议 - LICENSE: MIT，约束代码 - ASSET_LICENSE.md: CC BY-NC-SA 4.0，约束表情包素材 - CONTRIBUTING.md: 投稿流程、commit 与分支规范、PR 自检清单 - CHANGELOG.md: Keep a Changelog 格式，1.0.0 首发条目 - .gitignore: 补充 macOS/Windows/IDE/Python/日志等忽略项 - .github/ISSUE_TEMPLATE/: bug / feature / question 三个模板 - .github/PULL_REQUEST_TEMPLATE.md: 含素材来源声明与自检清单 --- .github/ISSUE_TEMPLATE/bug_report.md | 56 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 35 +++ .github/ISSUE_TEMPLATE/question.md | 34 +++ .github/PULL_REQUEST_TEMPLATE.md | 65 +++++ .gitignore | 67 ++++++ ASSET_LICENSE.md | 85 +++++++ CHANGELOG.md | 48 ++++ CONTRIBUTING.md | 232 ++++++++++++++++++ LICENSE | 41 ++++ README.md | 279 ++++++++++++++++++++++ 10 files changed, 942 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/question.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 ASSET_LICENSE.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..38a5528 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,56 @@ +--- +name: 🐛 Bug 报告 +about: 报告一个让你遇到问题的 bug（前端 / API / 构建 / 素材缺失等） +title: '[Bug] ' +labels: bug +assignees: '' +--- + +## 描述 + +简洁清晰地描述这个 bug 是什么。 + +## 复现步骤 + +1. 打开 `https://meme.smyhub.com/...` +2. 点击 `...` +3. 选择 `...` +4. 看到 `...` 而预期是 `...` + +## 预期行为 + +你**期望**发生什么。 + +## 实际行为 + +实际发生了什么？错误信息、控制台报错、网络请求等。 + +## 截图 / 录屏 + +如果有的话，附上（拖拽到下面即可）。 + +## 环境 + +- 浏览器 / 版本：例如 Chrome 125.0 / Safari 17.5 / Firefox 127 +- 操作系统：例如 Windows 11 / macOS 14 / iOS 17 / Android 14 +- 设备：例如 PC / iPhone 14 / 小米 14 +- 页面 URL：例如 https://meme.smyhub.com/#白色小人 +- 影响的素材路径（如果是某张图坏了）：例如 `白色小人/123.webp` + +## 浏览器控制台 + +> 打开 DevTools（F12）→ Console 标签，把相关报错贴上来。 + +``` +// 在此粘贴 +``` + +## 额外信息 + +任何其他可能有用的上下文。 + +## 检查清单 + +- [ ] 我已经搜索过 [已有 Issue](https://github.com/shumengya/meme-api/issues?q=is%3Aissue) 确认没人提过 +- [ ] 如果是素材问题，确认是仓库里 / 站点上都看不到，而不是我本地缓存 +- [ ] 我没有在 Issue 里包含任何个人敏感信息 diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..faac19a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,35 @@ +--- +name: 💡 功能建议 +about: 对图库 / API / 构建流程提出改进建议 +title: '[Feature] ' +labels: enhancement +assignees: '' +--- + +## 这个功能解决什么问题？ + +简要说明痛点或动机。例如： +- "我每次都要手动选 HTML 宽度 240，希望有记忆" +- "想在手机端把图片长按保存" + +## 你想要的方案 + +描述你心中的实现方式。可以包括： +- UI 截图 / 草图 +- 交互流程 +- 对哪些 API / 文件有影响 + +## 备选方案 + +有没有考虑过别的做法？各自的优缺点？ + +## 额外信息 + +- 影响的页面 / API：例如 `https://meme.smyhub.com/`、`/memes.json` +- 是否愿意自己提 PR：是 / 否 / 待定 +- 关联 Issue（如果有）：#123 + +## 检查清单 + +- [ ] 我已经搜索过 [已有 Issue](https://github.com/shumengya/meme-api/issues?q=is%3Aissue) 确认没人提过 +- [ ] 我愿意按 [CONTRIBUTING.md](../../CONTRIBUTING.md) 提一个 PR（可选） diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..76b5e12 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,34 @@ +--- +name: ❓ 提问 / 求助 +about: 不知道怎么用 / 需要帮助 +title: '[Question] ' +labels: question +assignees: '' +--- + +## 我想做什么 + +简述你想达到的目的。 + +## 我已经试过的 + +- 看了 README 里的「...」部分 +- 搜了 Issues，没找到 +- ... + +## 困惑点 + +具体卡在哪？ + +## 截图 / 代码 + +如果方便，附上相关截图或代码片段。 + +## 环境 + +- 浏览器 / 设备 +- 访问的 URL + +## 检查清单 + +- [ ] 我已经搜索过 [已有 Issue](https://github.com/shumengya/meme-api/issues?q=is%3Aissue) 确认没人提过 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..886860c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,65 @@ +## 描述 + + + +## 关联 Issue + + + +Closes # + +## 变更类型 + +请打勾： + +- [ ] 🐛 Bug 修复（fix） +- [ ] ✨ 新功能（feat） +- [ ] 🎨 样式 / UI 调整（style） +- [ ] ♻️ 重构（refactor） +- [ ] ⚡ 性能优化（perf） +- [ ] 📝 文档（docs） +- [ ] 🔧 构建 / 脚本 / 配置（chore） +- [ ] 🖼 素材投稿（新表情包 / 新分类） + +## 改动内容 + + + +- +- +- + +## 涉及的文件 + + + +- [ ] `public/index.html` +- [ ] `public/meme/...`（素材） +- [ ] `scripts/generate-manifest.mjs` +- [ ] `转化.py` +- [ ] `public/memes.json`（清单，由 `npm run build` 自动重生成） +- [ ] `dist/memes.json`（构建产物，请确认未手动修改） +- [ ] 文档（README / CONTRIBUTING / CHANGELOG / 其他） +- [ ] GitHub 配置（Issue 模板 / PR 模板 / .github 目录） + +## 素材来源声明（仅素材投稿必填） + +- **来源**：原创 / 转载自 `xxx` / 协议 `CC BY 4.0` / ... +- **是否商用素材**：否 +- **是否涉及他人作品**：否 / 是，已附原始协议与作者 +- **协议确认**：我同意按 [CC BY-NC-SA 4.0](./ASSET_LICENSE.md) 发布 + +## 自检清单 + +- [ ] 我已经读了 [CONTRIBUTING.md](./CONTRIBUTING.md) +- [ ] 本地 `npm run build` 通过，`public/memes.json` 已重生成 +- [ ] 本地 `npm run dev` 跑过，浏览器实测没回归 +- [ ] 移动端（DevTools 切到 375px）布局没崩 +- [ ] 改动不引入新外部依赖 +- [ ] 没有把 `dist/`、`node_modules/`、`__pycache__/`、`*.pyc`、`原图/` 里的源文件等 commit 进去 +- [ ] 素材若涉他人，已在 PR 描述里写明出处与原始协议 +- [ ] 我已更新 [CHANGELOG.md](./CHANGELOG.md)（如适用） + +## 截图 / 录屏 + + diff --git a/.gitignore b/.gitignore index 30516fc..365482e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,74 @@ +# ----- 构建产物 ----- dist/ node_modules/ .wrangler/ + +# ----- 临时 / 私密 ----- .dev.vars +.env +.env.local +*.local +tmp/ +temp/ + +# ----- 日志 ----- *.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* + +# ----- Python ----- __pycache__/ +*.py[cod] +*$py.class *.pyc +.venv/ +venv/ +env/ +ENV/ +.python-version +.mypy_cache/ +.pytest_cache/ +.ruff_cache/ +*.egg-info/ + +# ----- 操作系统残留 ----- +# macOS +.DS_Store +.AppleDouble +.LSOverride +._* +# Windows +Thumbs.db +ehthumbs.db +ehthumbs_vista.db +Desktop.ini +$RECYCLE.BIN/ + +# ----- IDE / 编辑器 ----- +.idea/ +.vscode/ +*.swp +*.swo +*.swn +*~ + +# ----- 备份 ----- +*.bak +*.orig +*.rej + +# ----- 工具缓存 ----- +.eslintcache +.cache/ +.parcel-cache/ +.turbo/ + +# ----- 其它 ----- +# 视频/音频预览（避免误提交原始素材） +*.psd +*.ai +*.sketch +*.fig diff --git a/ASSET_LICENSE.md b/ASSET_LICENSE.md new file mode 100644 index 0000000..1e0d259 --- /dev/null +++ b/ASSET_LICENSE.md @@ -0,0 +1,85 @@ +# 素材使用许可（CC BY-NC-SA 4.0） + +本仓库中**所有表情包图片素材**（包括但不限于 `public/meme/`、`原图/`、`原图-已处理/` 目录下的所有 `.webp`、`.gif`、`.png`、`.jpg` 等图像文件）适用本许可。 + +> 本文件**仅约束素材**。本仓库的**代码**、**文档**、**配置文件**适用 [LICENSE](./LICENSE) 中规定的 **MIT 协议**。 + +--- + +## 中文摘要（仅供参考，完整条款以英文原文为准） + +你可以： + +- ✅ **共享** — 复制、转载、在其他网站 / 博客 / 聊天工具中使用 +- ✅ **改编** — 二次加工、混剪、做自己的表情包 +- ✅ **署名** — 需要给原作者 / 本仓库署名 + +在以下条件下： + +- 📛 **署名（BY）** — 必须标明原作者 / 来源链接，**并标明是否做了修改** +- 🚫🚫 **非商用（NC）** — **不得用于任何商业目的** +- 🔁 **相同方式共享（SA）** — 如果你改编了，必须用**同样的 CC BY-NC-SA 4.0** 协议发布 + +## 完整法律文本 + +本作品采用 [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans) 协议许可。 + +访问以下链接查看完整条款： + +- 🇨🇳 简体中文： +- 🇺🇸 English： + +## 推荐署名格式 + +在使用本仓库的表情包时，建议在可被看见的地方附上以下署名之一： + +``` +素材来自：meme-api (https://github.com/shumengya/meme-api) +许可协议：CC BY-NC-SA 4.0 +``` + +如果你转载的是**单张表情**，可以简化为： + +``` +来源：shumengya/meme-api (CC BY-NC-SA 4.0) +``` + +## 关于商用 + +CC BY-NC-SA 的 **NC（NonCommercial）** 含义： + +- 🚫 不得用于售卖、付费内容、广告变现、商品印刷等任何**直接或间接**产生商业收益的场景 +- ✅ 私人聊天、个人博客 / 哔哔 / Telegram 频道、**不盈利**的社交账号可放心使用 +- ❓ 不确定？默认**视为商用**，或单独联系作者获取书面授权 + +如确有商用需求（广告、表情商店、付费内容、商品等），请提 [Issue](https://github.com/shumengya/meme-api/issues) 或直接联系作者协商。 + +## 关于投稿 + +向本仓库提交 PR 投稿素材，即表示你： + +1. 确认你对所投稿素材拥有合法分发权利（自己原创 / 协议允许 / 来源已授权） +2. 同意本仓库按 **CC BY-NC-SA 4.0** 协议发布你的投稿 +3. 同意其他人在遵守上述协议的前提下使用、改编、再分发你的投稿 + +如果你的素材使用了**他人的原始素材**，请在 PR 描述里写明出处与原始协议。 + +## 侵权处理 + +如果你认为本仓库的某张表情包**侵犯了你的合法权益**（版权、肖像权、商标等），请： + +1. 在仓库提一个 Issue 说明情况（推荐，便于追踪） +2. 或通过 GitHub 主页 找到联系方式 + +收到通知后，作者会在合理时间内**核实、删除或调整**相关内容，并对历史仓库做必要的回滚。 + +## 关于本协议的选择 + +- 为什么不是 MIT？表情包是**艺术作品 / 二次创作**，加上 **NC** 可以避免被无差别商用剽窃，加上 **SA** 可以让衍生作品保持开放。 +- 为什么不是 CC BY-SA？NC 限制可以保护作者署名权益，避免"我做的素材被人用在付费壁纸 APP 里"。 + +--- + +
+Last updated: 2026-06-04 +
diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f8d8605 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,48 @@ +# 更新日志 + +本项目的所有**重要变更**都会记录在此文件。 + +格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)， +版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。 + +> 表情包素材的新增 / 删除 **不**计入版本号，详情看 Git 提交历史。 + +## [Unreleased] + +### 计划中 +- 给图库前端加 lightbox 预览（点击放大、左右切换） +- 在图库首页显示每个分类的封面图 +- 素材缩放阈值参数化（支持多档位 CDN 输出） + +## [1.0.0] - 2026-06-04 + +### 新增 +- 仓库首次**公开**整理：补齐 README、LICENSE、CONTRIBUTING、CHANGELOG、Issue / PR 模板 +- 双协议声明：代码 MIT，表情包素材 CC BY-NC-SA 4.0 +- 收录 **51 个分类、~2600+ 张**表情包（WebP / GIF） +- 图库前端（`public/index.html`）：分类侧边栏 + 搜索 + 移动端 4 列 / 桌面 12 列网格 +- 一键复制 URL / Markdown / HTML（HTML 宽度 96–400px 可记忆） +- 一键下载原图 +- 在线 API 说明页：`https://meme.smyhub.com/readme/` +- JSON 公开 API：`/memes.json`（兼容 `/api/v1/memes`），已配置 CORS +- Python 一键处理脚本 `转化.py`（Pillow，多线程、动图 WebP→GIF、zip 批处理） +- Node 构建脚本 `scripts/generate-manifest.mjs`（仅生成清单，素材不重处理） +- Cloudflare Pages 部署支持：Git 集成 + wrangler CLI 双通道 + +### 安全 / 性能 +- 静态站点，**无服务端**，无任何用户数据收集 +- 所有外链静态资源（fonts、analytics 等）**未引入** +- CORS 头只对 `memes.json` 与 `/api/v1/memes` 开启，不影响其他资源 + +## 历史 + +在 1.0.0 之前，仓库作为个人项目维护，无版本号 / 变更日志。 + +[Unreleased]: https://github.com/shumengya/meme-api/compare/main...HEAD +[1.0.0]: https://github.com/shumengya/meme-api/releases/tag/v1.0.0 + +--- + +
+本文件由维护者手工维护，欢迎在 PR 中追加。 +
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..74a8116 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,232 @@ +# 投稿指南 🤝 + +非常欢迎你一起完善这个表情包图库！这份文档说明**怎么提交素材 / 修复 / 功能**才能又快又稳被合入。 + +> 阅读前请先看一眼 [README](./README.md) 和 [ASSET_LICENSE](./ASSET_LICENSE.md)，了解项目结构与协议。 + +## 目录 + +- [我能贡献什么？](#-我能贡献什么) +- [我该 fork 哪个分支？](#-我该-fork-哪个分支) +- [提 Issue](#-提-issue) +- [素材投稿流程](#-素材投稿流程) +- [代码 / 文档投稿](#-代码--文档投稿) +- [约定与规范](#-约定与规范) +- [本地自检](#-本地自检) +- [PR 流程](#-pr-流程) +- [审核标准](#-审核标准) +- [行为准则](#-行为准则) + +## 🎁 我能贡献什么？ + +| 类型 | 说明 | +| --- | --- | +| 🖼 新表情 / 新分类 | 投到 `public/meme/<新分类>/` 下 | +| 🐛 修坏图 / 错图 | 替换、删除或重新分类 | +| 🌐 图库前端改进 | 修改 `public/index.html`（单文件，无构建） | +| ⚙️ 构建脚本改进 | 改 `scripts/generate-manifest.mjs` 或 `转化.py` | +| 📝 文档 | 改进 `README.md`、本文件、API 说明页 | +| 🧪 Bug 报告 / 体验建议 | 提 Issue | + +## 🌿 我该 fork 哪个分支？ + +**默认 `main` 分支。** 任何 PR 都基于 `main`。 + +预览分支 `preview` 是 wrangler 部署的临时产物，**不要**直接 PR 到那里。 + +## 🐞 提 Issue + +- **Bug 报告**：用 [Bug 报告模板](.github/ISSUE_TEMPLATE/bug_report.md)，按字段填好 +- **新功能 / 改进建议**：用 [功能建议模板](.github/ISSUE_TEMPLATE/feature_request.md) +- **侵权 / 删除请求**：标题加 `[takedown]`，并附素材路径和说明 + +## 🖼 素材投稿流程 + +### 0. 先确认你有分发权 + +只投**以下任一**的素材： + +- ✅ 你自己原创 / 自己画的表情包 +- ✅ 协议允许二次分发的素材（如 CC BY、CC BY-SA、公共领域） +- ✅ 你已经获得作者明确授权 + +**别投**：商用素材、明显盗图、官方美术资源（除非协议明确允许）。 + +### 1. 处理素材（推荐） + +> `转化.py` 会帮你自动编号、缩放、转格式；**不要**手动起 `1.webp` 这样的名字，编号是脚本加的。 + +```bash +# 拿一个新分类举例 +mkdir -p 原图/我的新分类 +cp ~/Downloads/表情.png 原图/我的新分类/ + +# 装 Pillow（一次性） +python -m pip install pillow + +# 转换：自动编号、统一 webp/gif、最长边缩放到 250px +python 转化.py + +# 把生成结果拷入发布目录 +cp -r 原图-已处理/我的新分类 public/meme/ +``` + +参数说明： + +| 参数 | 作用 | +| --- | --- | +| `--delete-sources` | 处理完删除 `原图/` 里的源文件（默认保留） | +| `--max-side 250` | 最长边像素，默认 250px | +| `--jobs 10` | 并行线程数 | + +### 2. 直接投到 `public/meme/` + +如果你的素材**已经**是 `N.webp` / `N.gif` 命名，且最长边 ≤ 250px，可以**直接**放到 `public/meme/<分类>/`，不跑 `转化.py`。脚本在生成清单时会自动识别已编号的素材。 + +### 3. 重新生成清单 + +```bash +npm run build +``` + +这一步会重写 `public/memes.json` 与 `dist/memes.json`，**请把这两个文件一起 commit**。 + +### 4. 提交 PR + +- **PR 标题**：`feat(meme): 新增 xxx 分类` 或 `fix(meme): 删除损坏的 白色小人/123.webp` +- **PR 描述**： + - 素材来源（自己画 / 转载自 xxx / 协议 xxxx） + - 大致数量和分类 + - 截图（可选） + +## 💻 代码 / 文档投稿 + +### 前端 + +- `public/index.html` 是**单文件**前端（HTML + 内联 CSS + 内联 JS，**无任何依赖**） +- 改完**直接刷新本地预览**就能看效果： + ```bash + npm run dev + # 浏览器打开 http://localhost:8788 + ``` +- 尽量保持： + - 移动端优先 → 桌面端 + - 暗色模式自适应 + - 键盘可达（`Tab`、`Enter`、`Esc`） + - 不引入外部依赖 + +### 构建脚本 + +- `scripts/generate-manifest.mjs` — Node 18+ ESM +- `转化.py` — Python 3.8+，只依赖 Pillow +- 改完跑 `npm run build` 验证 `memes.json` 生成正确 + +### 文档 + +- 写完后检查一下渲染效果：本地打开 `README.md` 看看排版 +- 文档用 **中文**；变量名、函数名、commit 标题用**英文** +- 引用外部链接优先官方文档 + +## 📐 约定与规范 + +### Commit 消息 + +遵循 [Conventional Commits](https://www.conventionalcommits.org/)： + +``` +feat(meme): 新增 黄仁勋 分类 +fix(meme): 替换损坏的 滑稽/3.webp +docs: 完善 README 的 API 文档 +style(frontend): 调整移动端栅格断点 +refactor(scripts): 拆分 generate-manifest.mjs +chore: 升级 wrangler 到 4.7 +``` + +允许类型：`feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `chore` / `ci` + +### 分支名 + +- `feat/<短描述>`：新功能 / 新分类 +- `fix/<短描述>`：修 bug +- `docs/<短描述>`：文档 +- `chore/<短描述>`：杂项 + +例：`feat/meme-add-minecraft-pack`、`fix/meme-broken-gifs` + +### 分类目录命名 + +- 用**清晰的中文**，避免过长的字串 +- 不要带空格（用空格的话在 URL 里得编码，体验差） +- 不要带特殊符号 `/`、`\`、`#`、`?` +- 想拆同主题的子分类就再加一个目录，例如 `抹茶旦旦2` + +### 素材命名 + +- **不要**自己命名；让 `转化.py` 续号 +- 已经手动起好的也 OK（`1.webp` / `2.gif` 这种），脚本会从已有最大编号续起 + +### 文件格式 + +- 静态图：`.webp`（默认 lossless，质量 + 体积兼顾） +- 动图：`.gif`（Pillow 转码；WebP 动图也会被转成 GIF 提升兼容性） +- 缩放：最长边 **250px** +- 单张建议 ≤ **30KB**；动图 ≤ **100KB** + +## ✅ 本地自检 + +提交前请跑一遍： + +```bash +# 1. 构建通过、清单生成正常 +npm run build + +# 2. 本地预览，检查图库显示、复制/下载、侧边栏等 +npm run dev + +# 3. （可选）检查素材大小 +du -sh public/meme/<新分类>/ +ls -la public/meme/<新分类>/ | head +``` + +确认： + +- [ ] 新分类在侧边栏出现，编号连续无跳号 +- [ ] 点开任意一张能正常复制 URL / Markdown / HTML / 下载 +- [ ] 移动端（DevTools 切到 375px）布局没崩 +- [ ] 没有把 `dist/`、`node_modules/`、`__pycache__/`、`*.pyc` 等 commit 进去 + +## 🔁 PR 流程 + +1. Fork → 新分支 → 改代码 / 投素材 +2. `npm run build` 自检 +3. 提 PR 到 `main` +4. 描述清楚改了什么；附截图（如有 UI 变化） +5. 等 CI / 维护者 review +6. 必要的话按 review 改一轮 +7. 合并后 Cloudflare Pages 会自动部署 + +## 🧐 审核标准 + +PR 被合的优先级： + +- ✅ 修复真实 bug +- ✅ 引入来源清晰的新素材 +- ✅ 改进图库体验（无障碍 / 性能 / 暗色） +- ✅ 改进文档可读性 +- ⚠️ 大批量素材（> 200 张）建议先开 Issue 沟通 +- ❌ 协议不清晰的素材 +- ❌ 引入外部依赖（CDN 库、构建工具）的"重"改动 +- ❌ 与项目无关的"小改"（拼写错误除外） + +## 🫶 行为准则 + +- 友善、尊重、就事论事 +- 拒绝任何形式的骚扰、歧视、人身攻击 +- 提 Issue / 评论前先搜一下避免重复 +- 不确定时先问，错了就改 + +违反行为准则的评论 / PR 会被关闭，屡次违反会被封禁。 + +--- + +有任何问题，欢迎在 [Issue](https://github.com/shumengya/meme-api/issues) 里沟通。谢谢你的贡献！🌱 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4855131 --- /dev/null +++ b/LICENSE @@ -0,0 +1,41 @@ +MIT License + +Copyright (c) 2024-2026 shumengya and meme-api contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +================================================================================ +NOTICE — 本仓库采用 双重许可 (Dual Licensing) +================================================================================ + +本 LICENSE 文件**仅适用于本仓库中的源代码部分**，包括但不限于： + - HTML / CSS / JavaScript 前端代码 + - Python 脚本（转化.py 等） + - Node.js 脚本（scripts/*.mjs） + - Cloudflare Pages 配置文件（_headers、_redirects 等） + - 文档（README.md、CHANGELOG.md、CONTRIBUTING.md 等 Markdown 文本） + +本仓库中**表情包素材**（`public/meme/` 目录下的所有 .webp / .gif 文件， +以及 `原图/`、`原图-已处理/` 下的所有图片）适用单独的协议，请参阅： + + -> ASSET_LICENSE.md （CC BY-NC-SA 4.0） + +简言之： + · 代码：MIT，最宽松可用，包括商用 + · 素材：CC BY-NC-SA 4.0，署名 + 非商用 + 相同方式共享 diff --git a/README.md b/README.md new file mode 100644 index 0000000..5aea7d7 --- /dev/null +++ b/README.md @@ -0,0 +1,279 @@ +
+ +# 萌芽表情包图库 meme-api + +一个部署在 **Cloudflare Pages** 的纯静态表情包图库 + 公开 API。 +打开网页就能翻、一键复制链接 / Markdown / HTML，也支持直链外链和 JSON 接口拉清单。 + +[![Site](https://img.shields.io/website?url=https%3A%2F%2Fmeme.smyhub.com&label=%E5%9C%A8%E7%BA%BF%E5%9B%BE%E5%BA%93&logo=cloudflare&style=flat-square)](https://meme.smyhub.com) +[![API](https://img.shields.io/badge/API-memes.json-orange?style=flat-square)](https://meme.smyhub.com/memes.json) +[![License: Code MIT](https://img.shields.io/badge/%E4%BB%A3%E7%A0%81-MIT-blue?style=flat-square)](./LICENSE) +[![License: Assets CC BY-NC-SA 4.0](https://img.shields.io/badge/%E7%B4%A0%E6%9D%90-CC%20BY--NC--SA%204.0-lightgrey?style=flat-square)](./ASSET_LICENSE.md) +[![GitHub stars](https://img.shields.io/github/stars/shumengya/meme-api?style=flat-square)](https://github.com/shumengya/meme-api/stargazers) +[![GitHub forks](https://img.shields.io/github/forks/shumengya/meme-api?style=flat-square)](https://github.com/shumengya/meme-api/network) +[![Last commit](https://img.shields.io/github/last-commit/shumengya/meme-api?style=flat-square)](https://github.com/shumengya/meme-api/commits/main) + +[在线浏览](https://meme.smyhub.com) · [API 文档](https://meme.smyhub.com/readme/) · [投稿](#-投稿指南) · [更新日志](./CHANGELOG.md) + +
+ +--- + +## ✨ 这是什么 + +| 端 | 说明 | +| --- | --- | +| 🌐 **网页图库** | 分类侧边栏 + 移动端 4 列 / 桌面 12 列网格，搜索、暗色模式、键盘可达 | +| 📋 **一键复制** | 点开任意表情可复制 URL / Markdown / HTML（HTML 宽度 96–400px 可选） | +| ⬇️ **原图下载** | 直接下载原图，文件名保持原编号 | +| 🔗 **静态直链** | `/meme/<分类>/<编号>.webp` 可被任何网页、博客、聊天工具直接引用 | +| 📜 **JSON API** | `/memes.json`（兼容 `/api/v1/memes`）返回完整清单，**已配置 CORS** | + +> 收录 **51 个分类、约 2600+ 张** WebP / GIF 表情包，全部经过统一处理：最长边缩放至 250px、动图统一存为 GIF。 + +## 🖼 截图 + +> 在线版： + +
+🖥️ 桌面端（点击展开） + +``` +┌──────────────────────────────────────────────────────────────┐ +│ 萌芽表情包图库ﾍ(=^･ω･^=)ﾉ 说明 · memes.json │ +├──────────┬───────────────────────────────────────────────────┤ +│ 分类 │ 白色小人 · 224 滑稽 · 282 金馆长熊猫 · 304 │ +│ 🔍 搜索… │ 抹茶旦旦 · 227 抹茶旦旦2 · 120 … │ +│ 全部 │ ┌────┬────┬────┬────┬────┬────┬────┬────┐ │ +│ 白色小人 │ │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ … │ │ +│ 白色小人2 │ └────┴────┴────┴────┴────┴────┴────┴────┘ │ +│ … │ (12 列 × 自动行，点击任意缩略图弹出操作面板) │ +└──────────┴───────────────────────────────────────────────────┘ +``` + +
+ +
+📱 移动端（点击展开） + +``` +┌────────────────────────┐ +│ 萌芽表情包图库 … │ +├────────────────────────┤ +│ ☰ 分类 │ +│ 白色小人 · 224 │ +│ 滑稽 · 282 │ +│ 金馆长熊猫 · 304 │ +│ … │ +├────────────────────────┤ +│ ┌──┬──┬──┬──┐ │ +│ │1 │2 │3 │4 │ (4 列) │ +│ ├──┼──┼──┼──┤ │ +│ │5 │6 │7 │8 │ │ +│ └──┴──┴──┴──┘ │ +└────────────────────────┘ +``` + +
+ +## 🚀 快速开始 + +### 在线使用 + +直接打开 ，分类、搜索、复制随便玩。 + +### 引用单张表情 + +任意 HTML / Markdown / 聊天工具里粘贴： + +```markdown +# Markdown +![哈哈](https://meme.smyhub.com/meme/%E7%99%BD%E8%89%B2%E5%B0%8F%E4%BA%BA/1.webp) +``` + +```html + +哈哈 +``` + +> 路径里的中文 `分类` 名必须 URL 编码；图库的「复制链接」按钮已帮你编好。 + +### 拉取完整清单 + +```bash +curl -sS "https://meme.smyhub.com/memes.json" +# 老接口仍兼容： +curl -sS "https://meme.smyhub.com/api/v1/memes" +``` + +返回结构（节选）： + +```json +{ + "generatedAt": "2026-05-19T13:01:45.229Z", + "categories": [ + { + "id": "白色小人", + "name": "白色小人", + "items": [ + { "file": "1.webp", "path": "白色小人/1.webp" }, + { "file": "2.webp", "path": "白色小人/2.webp" } + ] + } + ] +} +``` + +拼接规则：`{BASE}/meme/{category.id}/{item.file}`。 + +## 🛠 本地开发 + +> 需要 **Node.js ≥ 18** 和 **Python ≥ 3.8**（仅当你需要重新处理图片时才用得到 Python）。 + +```bash +# 1. 克隆 +git clone https://github.com/shumengya/meme-api.git +cd meme-api + +# 2. 安装依赖（只需要 wrangler，体积很小） +npm install + +# 3. 构建（生成 dist/，含 memes.json） +npm run build + +# 4. 本地预览（http://localhost:8788） +npm run dev +``` + +可选的构建变体： + +| 命令 | 作用 | +| --- | --- | +| `npm run build` | 默认构建。清单优先扫描 `public/meme/`（已拷入的成品），否则回退 `原图-已处理/` / `原图/` | +| `npm run build:manifest-from-source` | **强制**按 `原图-已处理/`（无则 `原图/`）生成清单，不看 `public/meme/` | +| `npm run dev` | 构建 + 起 `serve` 静态服务在 8788 端口 | +| `npm run deploy:preview` | 用 `wrangler` 部署到 Cloudflare Pages **预览**分支 | +| `npm run deploy:upload` | 用 `wrangler` 部署到 Cloudflare Pages **生产**分支（仅直连 CLI 的项目用） | + +## 📦 添加 / 处理新表情 + +`public/meme/` 里已经是**可直接部署的成品**（已编号、已缩放、动图已是 GIF）。 +当你拿到新的原图想加入，按下面流程走： + +```bash +# 1. 把未编号的源素材丢进 原图/<分类名>/ +mkdir -p 原图/我的新分类 +cp ~/Downloads/xxx.png 原图/我的新分类/ + +# 2. 装依赖（一次性） +python -m pip install pillow + +# 3. 转换：自动编号、统一 webp / gif、最长边缩放到 250px +python 转化.py +# 产物落到 原图-已处理/，原图默认保留；想清源可加 --delete-sources + +# 4. 拷入发布目录 +cp -r 原图-已处理/我的新分类 public/meme/ + +# 5. 重新生成清单 +npm run build +``` + +> `转化.py` 的细节（多线程、zip 批处理、WebP→GIF 动图等）见脚本顶部 docstring。 + +## 🚢 部署到 Cloudflare Pages + +### 方式 A：连接 Git（推荐） + +1. 在 Cloudflare 控制台创建 Pages 项目，连接本仓库 `main` 分支 +2. 构建设置： + - **构建命令**：`npm run build` + - **构建输出目录**：`dist` +3. 每次 `git push` 都会自动触发部署 + +### 方式 B：CLI 直传 + +```bash +npm install +npx wrangler login # 第一次需要登录 +npm run deploy:upload # 部署到生产 +# 或 +npm run deploy:preview # 部署到 preview 分支 +``` + +> Git 项目里 `wrangler pages deploy` 通常会落到**预览**环境，属正常。 + +## 🗂 项目结构 + +``` +meme-api/ +├── 原图/ # 源素材（未编号、可能未处理） +├── 转化.py # Python 一键处理脚本（Pillow） +├── scripts/ +│ └── generate-manifest.mjs # 生成 memes.json + 复制 public/ -> dist/ +├── public/ # 构建源（直接作为站点根被复制） +│ ├── index.html # 图库前端（单文件，零依赖） +│ ├── _headers # CORS 等响应头 +│ ├── _redirects # 兼容旧路径（/memes -> /） +│ ├── memes.json # 由脚本生成的清单 +│ ├── meme/ # 处理后的素材（已编号 .webp / .gif） +│ └── readme/index.html # 在线 API 说明页 +├── dist/ # 构建产物（git 忽略） +├── package.json +└── .gitignore +``` + +## ⚙️ 配置 + +| 位置 | 作用 | +| --- | --- | +| `public/_headers` | `memes.json` 和 `/api/v1/memes` 的 CORS 头（已开启 `*`） | +| `public/_redirects` | `/api/v1/memes` → `/memes.json`；`/memes{,/}` → `/` | +| `scripts/generate-manifest.mjs` | 清单生成策略、最大文件格式（`.webp/.gif`）、输出目录 | + +如果想换 CDN 域名，可以在前端 JS 里给 `memes.json` 加 `baseUrl` 字段（详见脚本注释）。 + +## 🤝 投稿指南 + +欢迎补充新分类、修复坏图、改善图库体验！开始前请先看 **[CONTRIBUTING.md](./CONTRIBUTING.md)**，重点： + +- 素材需是 **你自己有权分发** 的，或来源已明确允许 +- 分类目录用清晰中文名；编号脚本会自动续号 +- 一张图只发一个分类；动图尽量保留动画 +- 提交 PR 前跑一次 `npm run build` 自检 + +## 📝 更新日志 + +见 [CHANGELOG.md](./CHANGELOG.md)。 + +## 📄 许可证 + +本仓库**双重许可**，请分别阅读： + +| 内容 | 协议 | 链接 | +| --- | --- | --- | +| **代码**（HTML / JS / Python / Node 脚本、`_headers`、`_redirects` 等） | MIT | [LICENSE](./LICENSE) | +| **表情包素材**（`public/meme/` 下的所有 `.webp` / `.gif` 文件） | CC BY-NC-SA 4.0 | [ASSET_LICENSE.md](./ASSET_LICENSE.md) | + +简言之：代码随便用、商用随便；素材**署名 + 非商用 + 相同方式共享**。 +如果你投稿了素材，默认视为同意按 CC BY-NC-SA 4.0 发布；商用授权请单独联系。 + +## 🙏 致谢 + +- 所有为这个图库添砖加瓦的[贡献者](https://github.com/shumengya/meme-api/graphs/contributors) +- 各个表情包原图的原作者 / 出处方 +- [Cloudflare Pages](https://pages.cloudflare.com/) 提供静态托管 +- [Pillow](https://python-pillow.org/) 提供图片处理能力 + +## 📬 联系 + +- Issue / PR： +- 主页： + +--- + +
+本项目仅作表情包整理与分享；如素材涉及版权或肖像权问题，请提 Issue 或邮件联系，会第一时间处理。 +