字
字节笔记本
2026年2月22日
Halolight：基于 Next.js 14 的企业级管理后台模板
Halolight 是一个基于 Next.js 14 App Router 的现代化中文后台管理系统模板，内置可拖拽仪表盘、RBAC 权限管理、PWA 能力等丰富功能，适合快速搭建中后台应用。该项目在 GitHub 上已获得 142 stars，采用 TypeScript 编写，代码质量高且维护活跃。
项目简介
Halolight Admin Pro 是一个开源的企业级管理后台解决方案，由 h7ml 开发维护。它基于最新的 Next.js 技术栈构建，提供了完整的后台管理系统所需的核心功能，包括用户认证、权限管理、数据可视化、表格管理等。
核心特性
- Next.js 14 App Router + TypeScript：支持 PWA、SEO 优化与全路由类型安全
- Server Actions：内置用户、文档、日历、文件等服务端操作
- Tailwind CSS 4 + shadcn/ui：原子化样式、Radix UI 原语、流畅主题切换（深色/浅色/系统）
- 增强交互体验：framer-motion 动画、Command Menu 全局搜索、TabBar/KeepAlive、加载遮罩
- 状态与数据流：React Query 5 + Axios 请求层，Zustand 5 管理认证/仪表盘/导航/UI 设置等全局状态
- 可配置仪表盘：react-grid-layout 支持拖拽、添加/删除/重置、布局持久化到 localStorage
- 快捷设置面板：快速切换主题、导航栏、TabBar、页脚等布局选项
- Mock.js 集成：环境变量一键启用，无后端快速演示开发
- 完整 CI/CD：GitHub Actions 自动化测试、构建、安全审计
技术栈
| 技术 | 用途 |
|---|---|
| Next.js 14 | React 框架，App Router 模式 |
| React 19 | UI 组件库 |
| TypeScript | 类型安全 |
| Tailwind CSS 4 | 原子化 CSS 框架 |
| shadcn/ui | 基于 Radix UI 的组件库 |
| Zustand 5 | 状态管理 |
| React Query 5 | 服务端状态管理 |
| Axios | HTTP 请求库 |
| framer-motion | 动画库 |
| react-grid-layout | 可拖拽仪表盘布局 |
| Mock.js | 模拟数据 |
| Vitest | 单元测试 |
安装指南
前置要求
- Node.js >= 18
- pnpm >= 8（项目锁定 pnpm@10.23.0）
安装步骤
bash
# 克隆仓库
git clone https://github.com/halolight/halolight.git
cd halolight
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev开发服务器默认运行在 http://localhost:3000
启用 Mock 数据（可选）
bash
export NEXT_PUBLIC_MOCK=true
pnpm dev生产构建
bash
pnpm build
pnpm start环境变量配置
在项目根目录创建 .env.local 文件：
bash
# API 基础地址
NEXT_PUBLIC_API_URL=https://api.halolight.h7ml.cn
# 启用 Mock.js 拦截
NEXT_PUBLIC_MOCK=true
# 演示账号
NEXT_PUBLIC_DEMO_EMAIL=admin@halolight.h7ml.cn
NEXT_PUBLIC_DEMO_PASSWORD=123456
# 显示演示账号提示
NEXT_PUBLIC_SHOW_DEMO_HINT=true
# WebSocket 服务器地址
NEXT_PUBLIC_WS_URL=wss://ws.halolight.h7ml.cn
# 应用标题
NEXT_PUBLIC_APP_TITLE=Admin Pro
# 品牌名称
NEXT_PUBLIC_BRAND_NAME=Halolight常用脚本
| 命令 | 说明 |
|---|---|
pnpm dev | 启动开发服务器 |
pnpm build | 生产构建 |
pnpm start | 启动生产服务 |
pnpm lint | ESLint 检查 |
pnpm lint:fix | 自动修复 ESLint 问题 |
pnpm type-check | TypeScript 类型检查 |
pnpm test | 运行测试（watch 模式） |
pnpm test:run | 运行测试（单次执行） |
pnpm test:coverage | 生成覆盖率报告 |
项目结构
text
src/
├── actions/ # Server Actions
├── app/
│ ├── (auth)/ # 认证页分组
│ └── (dashboard)/ # 主业务分组
├── components/
│ ├── ui/ # shadcn/ui 基础组件
│ ├── auth/ # 认证相关组件
│ ├── layout/ # 布局组件
│ ├── dashboard/ # 仪表盘组件
│ └── data-table/ # 表格组件
├── config/ # 集中配置
├── hooks/ # React Query hooks
├── lib/ # 工具库
├── mock/ # Mock.js 数据
├── providers/ # 全局 Provider
├── stores/ # Zustand 状态管理
└── types/ # TypeScript 类型定义部署方式
Vercel（推荐）
点击一键部署：
Docker 部署
dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]构建并运行：
bash
docker build -t halolight .
docker run -p 3000:3000 halolightCI/CD 工作流
项目配置了完整的 GitHub Actions 工作流：
| Job | 说明 |
|---|---|
| lint | ESLint 检查 + TypeScript 类型检查 |
| test | 单元测试 + 覆盖率报告上传 |
| build | Next.js 生产构建 |
| security | 依赖安全审计 |
| dependency-review | PR 依赖变更检查 |
浏览器支持
- Chrome >= 90
- Firefox >= 88
- Safari >= 14
- Edge >= 90
项目链接
- 在线预览：https://halolight.h7ml.cn
- GitHub 仓库：https://github.com/halolight/halolight
- 问题反馈：https://github.com/halolight/halolight/issues
许可证
MIT License
分享: