KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #dsh-plugin #ai-agent #mcp #deepseek-harness

GameSiteTemplate

★ 7 Open GitHub ↗

a template for building website for iframe games using nextjs,react19,shadcn ui,taliwind css,next-intl and so on

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Next.js Game Site Template (游戏站模板)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个高度规范化、模块化的 Next.js 模板，专为快速搭建现代化小游戏网站而设计。本项目集成了最新的前端技术栈，并从一开始就考虑了国际化和最佳开发实践。

## ✨ 核心特性

-   **🚀 最新技术栈**:
    -   [Next.js 15+](https://nextjs.org/) (App Router)
    -   [React 19+](https://react.dev/)
    -   [TypeScript](https://www.typescriptlang.org/)
-   **🎨 UI & 样式**:
    -   [Tailwind CSS](https://tailwindcss.com/)
    -   [Shadcn UI](https://ui.shadcn.com/) - 可定制的精美组件
-   **🌍 国际化 (i18n)**:
    -   使用 `next-intl` 集成，专为 App Router 设计。
    -   **默认支持英文**，可轻松扩展其他语言。
-   **🔧 开发工具与规范**:
    -   [ESLint](https://eslint.org/) (遵循最新配置标准)
    -   详细的[开发规范文档](mdc:.cursor/rules/)，覆盖各个技术方面。
    -   遵循声明式和函数式编程范式。
-   **🧩 模块化设计**: 易于扩展和维护，方便快速迭代和定制。
-   **📱 响应式设计**: 移动优先，确保在各种设备上的良好体验。
-   **⚡ 性能优化**: 注重 Web Vitals，提供流畅的用户体验。

## 🛠️ 技术栈

-   Next.js 15+ (App Router)
-   React 19+
-   TypeScript
-   Tailwind CSS
-   Shadcn UI
-   ESLint
-   `next-intl` (国际化，专为 App Router)
-   `nuqs` (URL 状态管理)
-   `@stagewise/toolbar-next` (AI 辅助开发工具栏)

## 🚀 快速开始

要使用此模板创建新的游戏站点项目：

1.  **使用此模板创建新仓库**:
    -   点击 GitHub 上的 "Use this template" 按钮。
    -   或者，直接克隆此仓库 (请替换为您的实际仓库地址):
        ```bash
        git clone https://your-repository-url/gamesite-template.git your-new-game-project
        cd your-new-game-project
        ```

2.  **安装依赖**:
    ```bash
    npm install
    # or
    yarn install
    # or
    pnpm install
    ```

3.  **运行开发服务器**:
    ```bash
    npm run dev
    # or
    yarn dev
    # or
    pnpm dev
    ```
    项目将在 `http://localhost:3000` (遵循规范默认为 3000) 上运行。

4.  **开始定制**:
    -   修改 `app/page.tsx` 开始构建您的主页。
    -   根据您的需求添加或修改 Shadcn UI 组件。
    -   参考 `.cursor/rules/` 下的开发规范进行编码。

## 📁 项目结构概览

```
gamesite-template/
├── .cursor/rules/         # 详细的开发规范文档
├── app/                   # Next.js App Router 核心目录
│   ├── [locale]/          # 国际化路由根目录 (e.g., en/, es/)
│   │   ├── layout.tsx     # 带语言环境的根布局
│   │   ├── page.tsx       # 带语言环境的首页
│   │   └── (other-routes)/ # 其他国际化路由
│   └── layout.tsx         # （可选）非国际化根布局或模板
│   └── page.tsx           # （可选）非国际化首页或着陆页
├── components/            # 全局共享组件
│   └── ui/                # Shadcn UI 组件存放处 (默认)
├── messages/              # 国际化翻译文件 (e.g., en.json, es.json)
├── public/                # 静态资源
├── lib/                   # 工具函数 (例如: utils.ts 包含 cn 函数)
├── middleware.ts          # Next.js 中间件 (用于 next-intl 路由)
├── i18n.ts                # next-intl 配置文件
├── .gitignore
├── eslint.config.mjs      # ESLint 配置文件 (Flat Config)
├── next.config.ts         # Next.js 配置文件
├── package.json
├── postcss.config.mjs     # PostCSS 配置文件
├── README.md              # 项目说明 (就是您现在看到的文件)
└── tsconfig.json          # TypeScript 配置文件
```

## 📜 开发规范

为确保代码质量和开发效率，本项目制定了一系列详细的开发规范。请在开发前仔细阅读：

-   [通用编码风格指南](mdc:.cursor/rules/general-coding-style.mdc)
-   [Next.js 开发指南](mdc:.cursor/rules/nextjs-guidelines.mdc)
-   [React 开发指南](mdc:.cursor/rules/react-guidelines.mdc)
-   [TypeScript 开发指南](mdc:.cursor/rules/typescript-guidelines.mdc)
-   [ESLint 配置指南](mdc:.cursor/rules/eslint-guidelines.mdc)
-   [国际化 (i18n) 指南](mdc:.cursor/rules/i18n-guidelines.mdc)
-   [Tailwind CSS 使用指南](mdc:.cursor/rules/tailwind-css-guidelines.mdc)
-   [Shadcn UI 使用指南](mdc:.cursor/rules/shadcn-ui-guidelines.mdc)
-   [Next.js 15 异步 API 处理指南](mdc:.cursor/rules/nextjs15-async-apis.mdc)
-   [Next.js Hydration 错误调试指南](mdc:.cursor/rules/nextjs-hydration-debugging.mdc)

## 🌍 近期开发重点

-   **About Us 和 Contact Us 页面内容完善**:
    -   **About Us 页面**: 创建了完整的公司介绍页面，包含欢迎介绍、使命说明、服务特色列表、承诺声明和社区邀请等内容，展示了 GameSite 的品牌形象和价值主张。
    -   **Contact Us 页面**: 实现了简洁明了的联系方式页面，按照用户要求不使用表格形式，而是采用文字说明的方式，包含4种不同类型的联系邮箱（一般咨询、技术支持、商务合作、法律事务）、响应时间说明和联系前建议，方便用户根据不同需求选择合适的联系方式。
    -   在 `messages/en.json` 中添加了详细的翻译内容，保持与其他法律页面一致的专业风格和结构。
    -   两个页面均采用响应式设计，支持明暗主题切换，与网站整体设计风格保持一致。
-   **完整合规页面体系实现**:
    -   **隐私政策页面**: 创建了符合GDPR、CCPA等国际法规要求的详细隐私政策，包含信息收集、使用、共享、用户权利、数据安全等完整条款。
    -   **Cookie政策页面**: 实现了专业的Cookie使用说明，涵盖Cookie类型、用途、管理方式、法律依据等内容，确保符合欧盟ePrivacy指令要求。
    -   **服务条款页面**: 建立了完整的用户协议体系，包含服务描述、用户责任、知识产权、责任限制、争议解决等法律条款。
    -   **版权侵权通知程序页面**: 实现了完整的DMCA版权侵权通知流程说明，包括概述、下架通知、反通知程序、重复侵权者政策等。
    -   所有页面均采用响应式设计，支持明暗主题切换，内容专业且易读，确保网站法律合规性和用户体验。
    -   在 `messages/en.json` 中添加了数千行详细的翻译内容，提供完整的法律条款说明。
-   **ESLint错误修复与代码质量提升**:
    -   修复了所有TypeScript ESLint错误，确保项目能够成功构建。
    -   将所有 `any` 类型替换为正确的类型定义：`locale as (typeof routing.locales)[number]`。
    -   移除了未使用的导入：`CardHeader`、`CardTitle`（sidebar组件）和 `GameData`（多个页面组件）。
    -   修复了未使用的变量：将 `catch (error)` 改为 `catch` 以避免未使用变量警告。
    -   确保代码符合项目的ESLint规范，提高代码质量和可维护性。
-   **游戏图标系统实现**:
    -   创建了 `public/images/game-icons/` 目录用于存储游戏图标文件。
    -   将用户提供的 `snow_rider_3d.jpg` 图标移动到专用图标文件夹。
    -   更新了 `default-game.json` 和 `italian-brainrot-clicker.json` 中的图标链接，从占位符URL改为实际的本地图标路径。
    -   创建了 `lib/utils/game-icons.ts` 工具函数，提供图标路径管理、默认占位符处理等功能。
    -   在图标文件夹中添加了详细的README文档，说明文件命名规范、使用方法和注意事项。
    -   建立了完整的图标管理体系，支持多种图片格式（jpg, jpeg, png, webp），便于后续添加更多游戏图标。
-   **侧边栏配置模板化**:
    -   创建了 `lib/data/sidebar-config.json` 配置文件，统一管理侧边栏的所有内容（顶部按钮和游戏分类）。
    -   在 `lib/types.ts` 中添加了 `SidebarConfig`、`SidebarButton`、`SidebarCategory` 类型定义。
    -   创建了 `lib/data/sidebar.ts` 数据获取函数和 `app/api/sidebar-config/route.ts` API 路由。
    -   重构了 `components/layout/sidebar.tsx`，使其从JSON配置文件动态加载内容，提高了模板的可配置性和可维护性。
-   **修复 Hydration 错误与页面间距优化**:
    -   解决了 React Hydration Mismatch 错误，主要涉及 `InteractiveRating` 组件中 `localStorage` 的使用和 `next-themes` 的主题状态不一致问题。
    -   在 `InteractiveRating` 组件中添加了 `mounted` 状态，确保服务端和客户端初始渲染一致，只有在客户端挂载后才从 `localStorage` 加载数据。
    -   为 `ThemeProvider` 添加了 `suppressHydrationWarning` 属性来解决主题相关的 hydration 问题。
    -   在 `Sidebar` 组件中为主题切换按钮添加了 `mounted` 状态和 `disabled` 属性，防止在客户端挂载前的交互。
    -   优化了页面内容间距：在主容器中添加 `px-4 md:px-6` 类提供左右内边距，调整内容卡片的桌面端内边距，解决内容过于拥挤的视觉问题。
-   **集成 Stagewise AI 开发工具栏**:
    -   安装了 `@stagewise/toolbar-next` 包。
    -   在根布局 `app/[locale]/layout.tsx` 中集成了 `StagewiseToolbar` 组件。
    -   确保工具栏仅在开发模式 (`process.env.NODE_ENV === 'development'`) 下加载和显示。
-   **添加 Contact Us 页面**:
    -   创建了 `app/[locale]/contact-us/page.tsx` 页面组件。
    -   在 `messages/en.json` 中添加了相应的翻译文本。
-   **页脚免责声明内容与标题调整**:
    -   修改了 `messages/en.json`，将免责声明的标题与内容分离，确保内容不重复显示。
    -   更新了 `components/layout/footer.tsx` 以使用新的翻译键，现在免责声明标题明确为 "Disclaimer:"。
-   **页脚免责声明居中对齐**:
    -   调整了 `components/layout/footer.tsx` 中免责声明的文本对齐方式，使其在所有屏幕尺寸下均居中显示，以提升视觉协调性。
-   **页脚布局再次优化**:
    -   进一步调整了 `components/layout/footer.tsx` 的布局。免责声明现在单独占据一行，文本居中（大屏幕左对齐）。所有其他页脚链接（关于我们、联系我们、用户协议等）在其下方横向居中排列成一行（或根据空间自动换行）。
-   **页脚布局调整**:
    -   调整了 `components/layout/footer.tsx` 的布局，使其在桌面视图下更偏向横向均衡分布。免责声明区域占据约三分之二宽度，链接区域占据约三分之一宽度，并修复了免责声明文本的显示问题。
-   **Next.js 15 异步 API 修复**:
    -   修复了在 `about-us`, `privacy-policy`, `cookie-policy`, 和 `terms-of-use` 页面的 `generateMetadata` 函数中，因直接访问 `params.locale` 而未首先 `await params` 导致的错误。所有相关页面已遵循 `nextjs15-async-apis.mdc` 指南进行更新。
-   **页脚样式调整与多语言支持移除 (初期)**:
    -   将页脚 (`components/layout/footer.tsx`) 的背景颜色从深红色改回浅色系 (中性色)，使其与网站整体背景更协调。
    -   移除了中文语言支持：删除了 `messages/zh.json`，并更新了 `i18n/routing.ts` 中的 `locales` 配置，目前仅支持英文 (`en`)。
-   **页脚增强与合规页面创建**:
    -   创建了 "About Us", "Privacy Policy", "Cookie Policy", "Terms of Use" 的占位符页面 (`app/[locale]/[page_slug]/page.tsx`)。
    -   更新了 `messages/en.json` 和 `messages/zh.json` 以包含新页面和页脚链接的翻译。
    -   重构了 `components/layout/footer.tsx` 组件，使其包含免责声明、上述新页面的链接，以及 "Contact Us" 和 "Copyright Infringement Notice Procedure" 的链接（这些链接目前也指向占位符路径）。页脚样式已更新以接近参考图片。
-   **国际化配置统一与冗余文件清理**:
    -   将 `i18n.ts` 和 `middleware.ts` 的路由配置导入路径从根目录的 `routing.ts` 修改为 `i18n/routing.ts`。
    -   删除了根目录下多余的 `routing.ts` 文件，统一了国际化路由配置源。
-   **路由修复与国际化初步配置**:
    -   修复了"其他游戏"部分中默认游戏链接指向错误路径 (`/games/home`) 的问题，现在正确指向根目录 (`/`)。
    -   在 `components/game/play-other-games.tsx` 中，将 `next/link` 替换为从新建的 `i18n/navigation.ts` 导出的本地化 `Link` 组件。
    -   根据 `i18n-guidelines.mdc` 创建了 `i18n/routing.ts` 和 `i18n/navigation.ts` 文件，为后续完整的国际化配置打下基础。
-   **修复与数据更新**:
    -   解决了在动态游戏页面 (`app/[locale]/games/[slug]/page.tsx`) 中因 Next.js 15 未 `await params` 访问 `params.slug` 导致的运行时错误，遵循了 `nextjs15-async-apis` 指南。
    -   更新了 `italian-brainrot-clicker.json` 游戏数据文件，将其 `gameUrl` 修改为新的嵌入链接。
-   **组件与依赖修复**:
    -   解决了 `app/[locale]/layout.tsx` 中因 `toaster` 组件缺失导致的模块找不到错误。将已废弃的 `toaster` 组件替换为 Shadcn UI 推荐的 `sonner` 组件，并更新了相关导入。
    -   安装了缺失的 `@vercel/speed-insights` 和 `@vercel/analytics` 依赖包。
    -   重新创建了 `components/theme-provider.tsx` 文件，该文件是 `next-themes` 的必要封装，并修正了其内部的类型导入问题。
-   **动态游戏路由与页面实现**:
    -   创建了动态路由 `app/[locale]/games/[slug]/page.tsx` 用于展示单个游戏的详细信息。
    -   实现了 `generateStaticParams` 以支持在构建时为 `lib/data/games/` 目录下的游戏预渲染页面。
    -   `GamePage` 组件 (`games/[slug]/page.tsx`) 现在会根据 URL中的 `slug` 加载并显示对应游戏的完整信息，其 UI 布局和组件与主页保持一致（包括游戏展示、元数据、概述等）。
    -   在单个游戏页面上，"Play Other Games" 部分会正确显示所有其他游戏（包括默认主页游戏），并排除当前正在查看的游戏。
    -   重构了代码，将共享的 TypeScript 接口 (`GameData`, `PlayableGame`) 移至 `lib/types.ts`，并将数据获取函数 (`getGameBySlug`, `getDefaultGameData`, `getAllGames`) 移至 `lib/data/games.ts`，提高了代码的模块化和可维护性。
-   **动态游戏数据加载与内容更新 (增强)**:
    -   主页 (`app/[locale]/page.tsx`) 现在默认加载并显示 `lib/data/default-game.json` 的内容。
    -   `getAllGames` 函数已更新，现在会统一加载 `lib/data/default-game.json` 以及 `lib/data/games/` 目录下的所有游戏，形成一个完整的游戏列表。
    -   首页的 "Play Other Games" 部分现在会显示 `
-   **侧边栏样式更新**:
    -   重构了 `components/layout/sidebar.tsx` 组件，使用 Shadcn UI 的 `Card` 组件替换了原有的 `<aside>` 元素和自定义样式，使其外观与其他卡片元素（如游戏列表）更加统一和美观。
    -   更新了侧边栏中的明暗主题切换按钮，使其能够通过 `next-themes` 的 `useTheme` hook 实际切换应用的主题。
    -   调整了侧边栏高度约束，移除 `min-h-full` 类，使侧边栏卡片与右侧主游戏板块实现自然的等高对齐，提升页面视觉和谐性。
    -   在布局中为侧边栏添加了顶部间距（`pt-4`），确保侧边栏与导航栏保持适当距离，并与主内容区域的间距保持一致。
    -   最终调整侧边栏布局：恢复 `min-h-full` 类使侧边栏填满可用高度，同时在包含侧边栏和主内容的容器上添加垂直间距（`py-4`），确保与header和footer保持适当距离，实现更美观的页面布局。
    -   优化页面布局以支持 Google AdSense：在页面右侧添加了固定宽度容器（`w-48`），与左侧广告位对称，为 Google AdSense 预留展示空间。同时移除了主内容区域的右侧内边距，使内容与游戏卡片右侧对齐，实现更合理的空间分配。
    -   改善页面视觉对齐：调整了主页面游戏卡片的位置，移除其底部边距并调整主容器的顶部内边距，使游戏卡片与左侧侧边栏的顶部位置对齐，提升整体页面的视觉和谐性。
    -   实现等高对齐：为主页面容器和内容包装器添加 `min-h-full` 类，确保右侧游戏卡片区域与左侧侧边栏实现真正的等高对齐，创造更加和谐统一的页面布局效果。
    -   重新设计侧边栏布局：参考用户提供的设计图，重构侧边栏结构为三个区域：顶部的 "NEW GAMES" 和 "HOT GAMES" 大按钮、中间的 Light/Dark 主题切换器、底部的游戏分类列表，同时保持白色卡片背景，提升用户体验和视觉层次。

GameSiteTemplate

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README