docs: 完善仓库文档（README / LICENSE / CONTRIBUTING / CHANGELOG / Issue 与 PR 模板）
- 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: 含素材来源声明与自检清单
This commit is contained in:
56
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
56
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
@@ -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 里包含任何个人敏感信息
|
||||
35
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
35
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
@@ -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（可选）
|
||||
34
.github/ISSUE_TEMPLATE/question.md
vendored
Normal file
34
.github/ISSUE_TEMPLATE/question.md
vendored
Normal file
@@ -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) 确认没人提过
|
||||
65
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
65
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
@@ -0,0 +1,65 @@
|
||||
## 描述
|
||||
|
||||
<!-- 一两句话说清这个 PR 干了什么。 -->
|
||||
|
||||
## 关联 Issue
|
||||
|
||||
<!-- 用 `Closes #123` / `Fixes #123` 关联 issue；没关联的写 "无"。 -->
|
||||
|
||||
Closes #
|
||||
|
||||
## 变更类型
|
||||
|
||||
请打勾：
|
||||
|
||||
- [ ] 🐛 Bug 修复（fix）
|
||||
- [ ] ✨ 新功能（feat）
|
||||
- [ ] 🎨 样式 / UI 调整（style）
|
||||
- [ ] ♻️ 重构（refactor）
|
||||
- [ ] ⚡ 性能优化（perf）
|
||||
- [ ] 📝 文档（docs）
|
||||
- [ ] 🔧 构建 / 脚本 / 配置（chore）
|
||||
- [ ] 🖼 素材投稿（新表情包 / 新分类）
|
||||
|
||||
## 改动内容
|
||||
|
||||
<!-- 详细列出做了哪些改动。可以按文件 / 模块分点。 -->
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
|
||||
## 涉及的文件
|
||||
|
||||
<!-- 方便 reviewer 快速定位 -->
|
||||
|
||||
- [ ] `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)（如适用）
|
||||
|
||||
## 截图 / 录屏
|
||||
|
||||
<!-- UI 改动请务必附图；素材投稿可以附几张代表图。 -->
|
||||
67
.gitignore
vendored
67
.gitignore
vendored
@@ -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
|
||||
|
||||
85
ASSET_LICENSE.md
Normal file
85
ASSET_LICENSE.md
Normal file
@@ -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) 协议许可。
|
||||
|
||||
访问以下链接查看完整条款：
|
||||
|
||||
- 🇨🇳 简体中文：<https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans>
|
||||
- 🇺🇸 English：<https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode>
|
||||
|
||||
## 推荐署名格式
|
||||
|
||||
在使用本仓库的表情包时，建议在可被看见的地方附上以下署名之一：
|
||||
|
||||
```
|
||||
素材来自：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 主页 <https://github.com/shumengya> 找到联系方式
|
||||
|
||||
收到通知后，作者会在合理时间内**核实、删除或调整**相关内容，并对历史仓库做必要的回滚。
|
||||
|
||||
## 关于本协议的选择
|
||||
|
||||
- 为什么不是 MIT？表情包是**艺术作品 / 二次创作**，加上 **NC** 可以避免被无差别商用剽窃，加上 **SA** 可以让衍生作品保持开放。
|
||||
- 为什么不是 CC BY-SA？NC 限制可以保护作者署名权益，避免"我做的素材被人用在付费壁纸 APP 里"。
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Last updated: 2026-06-04</sub>
|
||||
</div>
|
||||
48
CHANGELOG.md
Normal file
48
CHANGELOG.md
Normal file
@@ -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
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>本文件由维护者手工维护，欢迎在 PR 中追加。</sub>
|
||||
</div>
|
||||
232
CONTRIBUTING.md
Normal file
232
CONTRIBUTING.md
Normal file
@@ -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) 里沟通。谢谢你的贡献！🌱
|
||||
41
LICENSE
Normal file
41
LICENSE
Normal file
@@ -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，署名 + 非商用 + 相同方式共享
|
||||
279
README.md
Normal file
279
README.md
Normal file
@@ -0,0 +1,279 @@
|
||||
<div align="center">
|
||||
|
||||
# 萌芽表情包图库 meme-api
|
||||
|
||||
一个部署在 **Cloudflare Pages** 的纯静态表情包图库 + 公开 API。
|
||||
打开网页就能翻、一键复制链接 / Markdown / HTML，也支持直链外链和 JSON 接口拉清单。
|
||||
|
||||
[](https://meme.smyhub.com)
|
||||
[](https://meme.smyhub.com/memes.json)
|
||||
[](./LICENSE)
|
||||
[](./ASSET_LICENSE.md)
|
||||
[](https://github.com/shumengya/meme-api/stargazers)
|
||||
[](https://github.com/shumengya/meme-api/network)
|
||||
[](https://github.com/shumengya/meme-api/commits/main)
|
||||
|
||||
[在线浏览](https://meme.smyhub.com) · [API 文档](https://meme.smyhub.com/readme/) · [投稿](#-投稿指南) · [更新日志](./CHANGELOG.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ✨ 这是什么
|
||||
|
||||
| 端 | 说明 |
|
||||
| --- | --- |
|
||||
| 🌐 **网页图库** | 分类侧边栏 + 移动端 4 列 / 桌面 12 列网格，搜索、暗色模式、键盘可达 |
|
||||
| 📋 **一键复制** | 点开任意表情可复制 URL / Markdown / HTML（HTML 宽度 96–400px 可选） |
|
||||
| ⬇️ **原图下载** | 直接下载原图，文件名保持原编号 |
|
||||
| 🔗 **静态直链** | `/meme/<分类>/<编号>.webp` 可被任何网页、博客、聊天工具直接引用 |
|
||||
| 📜 **JSON API** | `/memes.json`（兼容 `/api/v1/memes`）返回完整清单，**已配置 CORS** |
|
||||
|
||||
> 收录 **51 个分类、约 2600+ 张** WebP / GIF 表情包，全部经过统一处理：最长边缩放至 250px、动图统一存为 GIF。
|
||||
|
||||
## 🖼 截图
|
||||
|
||||
> 在线版：<https://meme.smyhub.com>
|
||||
|
||||
<details>
|
||||
<summary>🖥️ 桌面端（点击展开）</summary>
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 萌芽表情包图库ﾍ(=^･ω･^=)ﾉ 说明 · memes.json │
|
||||
├──────────┬───────────────────────────────────────────────────┤
|
||||
│ 分类 │ 白色小人 · 224 滑稽 · 282 金馆长熊猫 · 304 │
|
||||
│ 🔍 搜索… │ 抹茶旦旦 · 227 抹茶旦旦2 · 120 … │
|
||||
│ 全部 │ ┌────┬────┬────┬────┬────┬────┬────┬────┐ │
|
||||
│ 白色小人 │ │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ … │ │
|
||||
│ 白色小人2 │ └────┴────┴────┴────┴────┴────┴────┴────┘ │
|
||||
│ … │ (12 列 × 自动行，点击任意缩略图弹出操作面板) │
|
||||
└──────────┴───────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>📱 移动端（点击展开）</summary>
|
||||
|
||||
```
|
||||
┌────────────────────────┐
|
||||
│ 萌芽表情包图库 … │
|
||||
├────────────────────────┤
|
||||
│ ☰ 分类 │
|
||||
│ 白色小人 · 224 │
|
||||
│ 滑稽 · 282 │
|
||||
│ 金馆长熊猫 · 304 │
|
||||
│ … │
|
||||
├────────────────────────┤
|
||||
│ ┌──┬──┬──┬──┐ │
|
||||
│ │1 │2 │3 │4 │ (4 列) │
|
||||
│ ├──┼──┼──┼──┤ │
|
||||
│ │5 │6 │7 │8 │ │
|
||||
│ └──┴──┴──┴──┘ │
|
||||
└────────────────────────┘
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 在线使用
|
||||
|
||||
直接打开 <https://meme.smyhub.com>，分类、搜索、复制随便玩。
|
||||
|
||||
### 引用单张表情
|
||||
|
||||
任意 HTML / Markdown / 聊天工具里粘贴：
|
||||
|
||||
```markdown
|
||||
# Markdown
|
||||
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- HTML（宽度 240px，自适应） -->
|
||||
<img src="https://meme.smyhub.com/meme/%E7%99%BD%E8%89%B2%E5%B0%8F%E4%BA%BA/1.webp"
|
||||
alt="哈哈" loading="lazy" width="240"
|
||||
style="max-width:240px;width:100%;height:auto" />
|
||||
```
|
||||
|
||||
> 路径里的中文 `分类` 名必须 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：<https://github.com/shumengya/meme-api/issues>
|
||||
- 主页：<https://github.com/shumengya>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>本项目仅作表情包整理与分享；如素材涉及版权或肖像权问题，请提 Issue 或邮件联系，会第一时间处理。</sub>
|
||||
</div>
|
||||
Reference in New Issue
Block a user