{"id":45884114,"url":"https://github.com/TangSY/edge-next-starter","last_synced_at":"2026-03-13T02:01:17.407Z","repository":{"id":321422594,"uuid":"1083446890","full_name":"TangSY/edge-next-starter","owner":"TangSY","description":"An out‑of‑the‑box Next.js + Cloudflare full‑stack starter integrating Edge Runtime, D1 database, R2 storage, KV cache, Analytics Engine hooks, and a complete CI/CD pipeline.一个开箱即用的 Next.js + Cloudflare 全栈项目模板，集成 Edge Runtime、D1 数据库、R2 存储和完整的 CI/CD 流程。","archived":false,"fork":false,"pushed_at":"2026-02-27T05:58:32.000Z","size":554,"stargazers_count":455,"open_issues_count":0,"forks_count":92,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-27T10:22:08.116Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cloudflare-worker-template-prod.t-ac5.workers.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TangSY.png","metadata":{"files":{"readme":"README-zh.md","changelog":"CHANGELOG-zh.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T03:09:36.000Z","updated_at":"2026-02-27T05:58:35.000Z","dependencies_parsed_at":"2025-10-29T16:21:32.029Z","dependency_job_id":"d76a7614-d4bc-4d05-8eca-698ccb457e25","html_url":"https://github.com/TangSY/edge-next-starter","commit_stats":null,"previous_names":["tangsy/edge-next-starter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TangSY/edge-next-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangSY%2Fedge-next-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangSY%2Fedge-next-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangSY%2Fedge-next-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangSY%2Fedge-next-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TangSY","download_url":"https://codeload.github.com/TangSY/edge-next-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangSY%2Fedge-next-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30454982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"online","status_checked_at":"2026-03-13T02:00:07.565Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-27T15:00:30.027Z","updated_at":"2026-03-13T02:01:17.401Z","avatar_url":"https://github.com/TangSY.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[English](./README.md) | 简体中文\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n![vinext](https://img.shields.io/badge/vinext-Vite_+_Next.js-646CFF?style=flat\u0026logo=vite)\n![Next.js](https://img.shields.io/badge/Next.js-15.5.2-black?style=flat\u0026logo=next.js)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue?style=flat\u0026logo=typescript)\n![React](https://img.shields.io/badge/React-19.2.0-61DAFB?style=flat\u0026logo=react)\n![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3.4.17-38B2AC?style=flat\u0026logo=tailwind-css)\n![Cloudflare](https://img.shields.io/badge/Cloudflare-Workers-F38020?style=flat\u0026logo=cloudflare)\n![Prisma](https://img.shields.io/badge/Prisma-6.17.1-2D3748?style=flat\u0026logo=prisma)\n![better-auth](https://img.shields.io/badge/better--auth-Edge_Compatible-8B5CF6?style=flat)\n![Node.js](https://img.shields.io/badge/Node.js-≥22.0.0-339933?style=flat\u0026logo=node.js)\n![pnpm](https://img.shields.io/badge/pnpm-8.15.0-F69220?style=flat\u0026logo=pnpm)\n![License](https://img.shields.io/badge/License-MIT-green?style=flat)\n\n\u003c/div\u003e\n\n---\n\n# Next.js + Cloudflare Workers 全栈模板 (vinext)\n\n一个生产就绪的 Next.js + Cloudflare Workers 全栈项目模板，基于 [vinext](https://github.com/cloudflare/vinext)（Vite 驱动的 Next.js 重新实现）构建。集成 D1 数据库、R2 存储、KV 缓存、better-auth 认证、next-intl 国际化和完整的 CI/CD 流程 — 所有代码原生运行在 Cloudflare Workers 全球边缘网络上。\n\n## ✨ 特性\n\n### 核心技术栈\n\n- **[vinext](https://github.com/cloudflare/vinext)** - 基于 Vite 的 Next.js 重新实现（构建速度提升 4 倍，包体积缩小 57%）\n- **Next.js 15.5.2** - App Router + RSC（React Server Components）\n- **Cloudflare Workers** - 原生边缘部署（非 Pages）\n- **D1 Database** - 边缘端 SQLite 数据库\n- **R2 Storage** - 零出站费用的对象存储\n- **KV Storage** - 高性能键值缓存\n- **better-auth** - Edge 兼容的认证系统（邮箱密码 + Google OAuth）\n- **Tailwind CSS** - 实用优先的 CSS 框架\n\n### 开发工具\n\n- **Vite** - 下一代前端构建工具（通过 vinext）\n- **pnpm** - 快速、节省磁盘空间的包管理器\n- **Vitest** - 现代化的单元测试框架\n- **ESLint + Prettier** - 代码规范和格式化\n- **TypeScript** - 类型安全\n\n### 自动化流程\n\n- ✅ Vitest 覆盖核心仓储、数据库、缓存和存储客户端\n- ✅ 自动化 CI/CD 部署（带构建缓存优化）\n- ✅ 数据库迁移自动执行和验证\n- ✅ 多环境配置（开发/测试/生产）\n- ✅ API 速率限制（基于 KV 的滑动窗口算法）\n- ✅ 自动生成 CHANGELOG（基于 Conventional Commits）\n- ✅ **环境变量自动校验（Zod）**\n- ✅ **结构化日志和请求追踪（内置 Analytics 钩子，可扩展到 Analytics Engine）**\n- ✅ **数据库迁移自动校验脚本**\n\n## 📋 前置要求\n\n- **Node.js** \u003e= 22.0.0 (推荐使用 nvm 管理版本)\n- **pnpm** \u003e= 8.0.0\n- **Cloudflare 账户**\n- **Git**\n\n## 🚀 快速开始\n\n完整安装配置步骤请查看 **[快速开始指南](./QUICKSTART-zh.md)**。该文档覆盖依赖安装、Cloudflare 登录、资源创建、迁移执行与开发服务器启动的全流程，这里只保留入口说明。\n\n## 🌟 案例展示\n\n基于本模板构建的项目：\n\n- **[imgc AI](https://imgc.vip)** — 免费的 AI 图像生成平台，由 DALL-E 3 驱动。支持多种宽高比、多种艺术风格（电影级、摄影、动漫、数字艺术等）及提示词优化功能。具备闪电生成速度、隐私优先设计，无需注册即可无限免费使用。\n\n## 📁 项目结构\n\n```\ncloudflare-worker-template/\n├── app/                        # Next.js App Router\n│   ├── api/                   # API 路由（Edge Runtime）\n│   │   ├── health/           # 健康检查\n│   │   ├── users/            # 用户 CRUD 示例\n│   │   ├── posts/            # 文章 CRUD 示例\n│   │   └── upload/           # 文件上传示例\n│   ├── layout.tsx            # 根布局\n│   ├── page.tsx              # 首页\n│   └── globals.css           # 全局样式\n├── repositories/              # 数据访问层（Repository 模式）\n│   ├── index.ts              # Repository 工厂\n│   ├── user.repository.ts    # User 数据操作\n│   └── post.repository.ts    # Post 数据操作\n├── lib/                       # 工具库\n│   ├── api/                  # API 工具（响应格式、中间件、数据库包装器）\n│   ├── db/                   # D1 数据库客户端（Prisma 单例）\n│   ├── r2/                   # R2 存储客户端\n│   ├── cache/                # KV 缓存客户端\n│   ├── errors/               # 统一错误处理\n│   ├── logger/               # 日志系统\n│   └── utils/                # 通用工具\n├── components/                # React 组件\n├── types/                     # TypeScript 类型定义\n├── migrations/                # 数据库迁移文件（SQL）\n│   ├── 0001_init.sql         # 初始化表结构\n│   └── 002_example.sql.template\n├── prisma/                    # Prisma 配置\n│   └── schema.prisma         # 数据库模型定义\n├── scripts/                   # 自动化脚本\n│   └── seed.js               # 数据填充\n├── __tests__/                 # 测试文件\n│   ├── lib/                  # 单元测试\n│   └── api/                  # API 测试\n├── .github/workflows/         # GitHub Actions CI/CD\n│   ├── ci.yml                # 持续集成\n│   ├── deploy-test.yml       # 测试环境部署\n│   └── deploy-prod.yml       # 生产环境部署\n├── wrangler.toml              # 本地环境配置\n├── wrangler.test.toml         # 测试环境配置\n├── wrangler.prod.toml         # 生产环境配置\n├── .nvmrc                     # Node.js 版本\n├── .npmrc                     # pnpm 配置\n├── vitest.config.ts           # 测试配置\n└── package.json               # 项目配置\n```\n\n## 🛠️ 常用命令\n\n详细命令说明请查看 **[开发指南](./docs/DEVELOPMENT-zh.md)**\n\n```bash\n# 开发\npnpm dev                    # vinext 开发服务器（Vite + Workers 运行时）\n\n# 测试\npnpm test                   # 运行所有测试\npnpm run test:watch         # 监听模式\n\n# 构建和部署\npnpm build                  # 构建应用（vinext + Vite）\npnpm deploy                 # 部署到 Cloudflare Workers\n```\n\n## 🔄 持续集成/部署\n\n详细部署配置和流程请查看 **[部署指南](./docs/DEPLOYMENT-zh.md)**\n\n- **持续集成**：每次 push 自动运行测试、类型检查和构建\n- **自动部署**：\n  - `develop` 分支 → 测试环境\n  - `main` 分支 → 生产环境\n\n### 配置密钥\n\n在仓库设置中添加：\n\n- `CLOUDFLARE_API_TOKEN`\n- `CLOUDFLARE_ACCOUNT_ID`\n\n## 📦 API 示例\n\n### 健康检查\n\n```bash\ncurl https://your-domain.com/api/health\n```\n\n### 用户管理（带缓存）\n\n```bash\n# 获取所有用户\ncurl https://your-domain.com/api/users\n\n# 创建用户\ncurl -X POST https://your-domain.com/api/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"user@example.com\", \"name\": \"张三\"}'\n```\n\n### 文件上传到 R2\n\n```bash\n# 通过 API 上传文件\ncurl -X POST https://your-domain.com/api/upload \\\n  -F \"file=@image.jpg\"\n\n# 下载文件\ncurl https://your-domain.com/api/upload?key=uploads/1234567890-image.jpg\n\n### 上传页面（R2 演示）\n\n- 访问 `/upload` 试用浏览器端上传 UI（调用 `/api/upload` 并展示预览）。\n```\n\n## 🧪 测试\n\n```bash\npnpm test                   # 运行核心单元测试\npnpm run test:coverage      # 查看覆盖率\n```\n\n测试覆盖：D1 数据库、R2 存储、KV 缓存、错误处理\n\n## 🌍 多环境配置\n\n- **开发环境**：`wrangler.toml` - 本地开发\n- **测试环境**：`wrangler.test.toml` - `develop` 分支自动部署\n- **生产环境**：`wrangler.prod.toml` - `main` 分支自动部署\n\n详细的绑定名称、Secrets 以及数据填充命令请参阅 [docs/ENVIRONMENTS-zh.md](./docs/ENVIRONMENTS-zh.md)。\n\n## 📈 Cloudflare 免费额度（Workers Free）\n\n以下为在 Cloudflare Workers Free 计划下的主要免费额度概览（以官方当前文档为准，可能随时调整）：\n\n- Workers\n  - 每日请求：100,000 次\n  - CPU 时间：每次请求 10 毫秒\n  - Workers 数量：无限制\n\n- D1 Database（数据库）\n  - 数据库数量：10 个\n  - 总存储空间：5 GB（所有数据库共享）\n  - 每日行读取：5,000,000 次\n  - 每日行写入：100,000 次\n\n- R2 Storage（对象存储）\n  - 存储空间：每月 10 GB\n  - Class A 操作（写入/删除等）：每月 1,000,000 次\n  - Class B 操作（读取）：每月 10,000,000 次\n  - 出站流量（Egress）：永久免费（$0）\n\n- KV Storage（键值缓存）\n  - 总存储空间：1 GB\n  - 每日读取操作：10,000,000 次\n  - 每日写入/删除/列出操作：100,000 次（合计）\n\n- Analytics Engine（分析引擎）\n  - 每日数据写入（Data points written）：100,000 个\n  - 每日数据读取（Read queries）：10,000 次\n\n提示：若需更高配额或更强功能，可升级 Workers 付费计划；同时建议在生产环境通过特性开关接入 Analytics Engine，在开发/测试环境保持日志或 KV/D1 作为降级方案。\n\n## 💡 开发最佳实践\n\n详细的开发规范请查看 **[开发指南](./docs/DEVELOPMENT-zh.md)**\n\n1. **强制使用 pnpm** - 项目已配置自动检查\n2. **遵循代码规范** - 提交前自动执行 ESLint 和 Prettier\n3. **编写测试** - 为新功能添加测试用例\n4. **使用数据库迁移** - 通过迁移文件管理数据库变更\n\n## 🔧 常见问题\n\n常见的开发与部署疑难项已经录入专题文档：\n\n- 开发排障请参见 [开发指南的常见问题章节](./docs/DEVELOPMENT-zh.md#常见问题)\n- 部署排障请参见 [部署指南的故障排查章节](./docs/DEPLOYMENT-zh.md#故障排查)\n\n## 📚 相关文档\n\n### 核心文档\n\n- [QUICKSTART-zh.md](./QUICKSTART-zh.md) - 快速开始指南\n- [CHANGELOG-zh.md](./CHANGELOG-zh.md) - 更新日志\n\n### 技术文档\n\n- [ARCHITECTURE-zh.md](./docs/ARCHITECTURE-zh.md) - 项目架构说明\n- [DEVELOPMENT-zh.md](./docs/DEVELOPMENT-zh.md) - 开发指南\n- [DEPLOYMENT-zh.md](./docs/DEPLOYMENT-zh.md) - 部署指南\n- [ENVIRONMENTS-zh.md](./docs/ENVIRONMENTS-zh.md) - 环境绑定与密钥清单\n\n### 专项文档\n\n- [REPOSITORY-zh.md](./docs/REPOSITORY-zh.md) - Repository 模式指南\n- [MIGRATIONS-zh.md](./docs/MIGRATIONS-zh.md) - 数据库迁移指南\n\n## 🔗 技术文档\n\n- [vinext](https://github.com/cloudflare/vinext) | [Next.js](https://nextjs.org/docs) | [Vite](https://vite.dev/)\n- [Cloudflare Workers](https://developers.cloudflare.com/workers/) | [D1 Database](https://developers.cloudflare.com/d1/) | [R2 Storage](https://developers.cloudflare.com/r2/)\n- [better-auth](https://www.better-auth.com/) | [Prisma](https://www.prisma.io/docs)\n\n## 🎯 快速开始业务开发\n\n拿到这个模板后：\n\n1. ✅ 按照 [快速开始指南](./QUICKSTART-zh.md) 完成初始化\n2. ✅ 在 `app/` 目录下编写页面和 API\n3. ✅ 提交代码，CI/CD 自动测试和部署\n4. ✅ 专注业务逻辑，无需关心基础设施\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTangSY%2Fedge-next-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTangSY%2Fedge-next-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTangSY%2Fedge-next-starter/lists"}