Skip to content

tanchaowen84/GameSiteTemplate

BranchesTags

Repository files navigation

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

License: MIT

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

✨ 核心特性

  • 🚀 最新技术栈:
  • 🎨 UI & 样式:
  • 🌍 国际化 (i18n):
    • 使用 next-intl 集成，专为 App Router 设计。
    • 默认支持英文，可轻松扩展其他语言。
  • 🔧 开发工具与规范:
    • ESLint (遵循最新配置标准)
    • 详细的开发规范文档，覆盖各个技术方面。
    • 遵循声明式和函数式编程范式。
  • 🧩 模块化设计: 易于扩展和维护，方便快速迭代和定制。
  • 📱 响应式设计: 移动优先，确保在各种设备上的良好体验。
  • ⚡ 性能优化: 注重 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" 按钮。
    • 或者，直接克隆此仓库 (请替换为您的实际仓库地址): 
      git clone https://your-repository-url/gamesite-template.git your-new-game-project
cd your-new-game-project

  2. 安装依赖:

    npm install
# or
yarn install
# or
pnpm install

  3. 运行开发服务器:

    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 配置文件

📜 开发规范

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

  • 通用编码风格指南
  • Next.js 开发指南
  • React 开发指南
  • TypeScript 开发指南
  • ESLint 配置指南
  • 国际化 (i18n) 指南
  • Tailwind CSS 使用指南
  • Shadcn UI 使用指南
  • Next.js 15 异步 API 处理指南
  • Next.js Hydration 错误调试指南

🌍 近期开发重点

  • 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 主题切换器、底部的游戏分类列表，同时保持白色卡片背景，提升用户体验和视觉层次。

About

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

Resources

Readme
Activity

Stars

7 stars

Watchers

1 watching

Forks

8 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages