Vibe Template CF

纯前端版本 | Worker 版本

Vibe Template CF

基于 Next.js 16、Tailwind CSS v4、Hono 和 Cloudflare Pages 的现代化全栈开发模板。

✨ 核心功能

• 全栈架构: Monorepo (Frontend + Functions + Shared)
• 前端框架: Next.js 16 (App Router) + React 19
• 后端运行时: Cloudflare Pages Functions + Hono
• 样式方案: Tailwind CSS v4 + shadcn/ui
• 状态管理: Zustand
• 类型安全: TypeScript + Shared Types

🚀 快速开始

前置要求

• Node.js 18+
• Cloudflare 账号（免费）

本地开发

本地开发

1. 获取项目

git clone https://github.com/DJChanahCJD/vibe-template-cf.git <your-project-name>
cd <your-project-name>

2. 重置仓库 (推荐)

移除原有远程仓库关联，并开启新项目历史。

git remote remove origin

# 1. 先移除旧的.git目录（Windows）
rm -r -fo .git
# 2. 重新初始化Git仓库
git init

3. 安装依赖

# 在根目录运行，自动安装所有 Workspaces 依赖
npm install

4. 启动项目

npm run dev

第一次启动需要构建前端 npm run build，后续启动直接 npm run dev 即可。

5. 访问网站

• 前端：http://localhost:3000
• 后端：http://localhost:8788 (由 Wrangler 代理)

Tip

开发环境下密码为123456（在访问 /admin 页面时需要） 修改 functions 代码后，可运行 npm run ci-test 快速测试功能是否正常。

---

📦 Cloudflare 部署

1. 创建 Pages 项目

Fork 本项目，然后在 Cloudflare Dashboard 创建 Pages 项目：

• 构建命令: npm run build
• 构建输出目录: frontend/out

2. 配置环境变量

在 Pages 项目的设置中添加以下环境变量：

PASSWORD=your_password          # 密码

3. 配置 D1 数据库

配置 KV 绑定步骤类似

在 Cloudflare Dashboard 创建 D1 数据库，并绑定到 Pages 项目：

1. 进入 Workers & Pages
2. 选择当前 Pages 项目
3. 进入 Settings → Bindings
4. 添加 D1 database binding
5. 变量名填写 your_db（改为你实际使用的变量名）
6. 选择你的 D1 数据库并重新部署

本地开发已通过 npm run dev 中的 --d1 your_db 挂载本地 D1，不需要在 wrangler.jsonc 写入 database_id。

可通过 GET /db/health 检查 D1 绑定是否正常。

4. 重试部署

回到部署页面重试部署，让环境变量生效。

📂 项目结构

vibe-template-cf/
├── frontend/                          # Next.js 前端应用
│   ├── app/                           # 页面与布局 (App Router)
│   ├── components/
│   │   └── ui/                        # shadcn/ui 组件库
│   ├── hooks/                         # React 自定义 Hooks
│   ├── lib/
│   │   ├── api/                       # API 客户端 (auth, client, config)
│   │   └── utils/
│   │       └── cache.ts               # 前端缓存工具
│   ├── public/                        # 静态资源
│   └── stores/                        # Zustand 状态管理
│
├── functions/                         # Cloudflare Pages Functions 后端 (Hono)
│   ├── [[path]].ts                    # 入口路由
│   ├── middleware/
│   │   ├── auth.ts                    # 认证中间件
│   │   └── cors.ts                    # CORS 中间件
│   ├── routes/
│   │   ├── auth.ts                    # 认证路由
│   │   ├── db.ts                      # D1 数据库路由
│   │   └── proxy.ts                   # 代理路由
│   ├── types/                         # 后端类型定义
│   └── utils/
│       ├── auth.ts                    # 认证工具
│       ├── cache.ts                   # 后端缓存工具
│       ├── kv.ts                      # KV 存储工具
│       ├── response.ts                # 响应格式化工具
│       └── proxy/                     # 代理工具集
│           ├── fetch.ts               # 代理请求封装
│           ├── headers.ts             # 请求头处理
│           ├── site-rules.ts          # 站点规则
│           └── url-guard.ts           # URL 安全校验
│
├── shared/                            # 前后端共享代码
│   └── src/
│       └── types/                     # 共享类型定义 (Cloudflare 环境类型等)
│
├── test/                              # 集成测试
├── .husky/                            # Git Hooks (pre-commit)
├── wrangler.jsonc                     # Cloudflare Wrangler 配置
└── package.json                       # 根 Monorepo 配置

## 🔍 参考资料

- [Cloudflare API](https://developers.cloudflare.com/api)

## TODO

- [x] 引入 Husky 做 pre-commit 检查
- [x] 引入 D1 数据库支持
- [x] 引入最小 PWA 支持

## 🧰 开发检查

项目已配置 Husky pre-commit hook：

- `lint-staged` 会格式化 staged 文件

## 🤝 Contributing

欢迎提交 **Issue** 反馈问题或建议新功能，也欢迎 **Pull Request** 一起完善项目！
觉得有用的话，点个 ⭐️ 支持一下吧！