Shadboard是一款基于 Next.js 15 和 shadcn/ui 构建的开源免费后台面板模板（Admin Dashboard），内置登录认证、多语言、主题定制、仪表盘图表等开箱即用功能。本安装教程带你用3个步骤在本地跑起来 Shadboard 管理后台，零基础也能轻松上手 🚀

一、Shadboard 是什么？能做什么？

在动手之前，先花30秒了解这个后台面板模板能给你什么：

它提供两个版本，按需选择：

• Full Kit（full-kit/）：功能全量版，包含登录认证、i18n、全部演示页面，适合直接作为项目起点；
• Starter Kit（starter-kit/）：极简版，只保留核心布局组件，适合想从零搭自己结构的开发者。

📖 详细对比见官方文档页面 kits/page.mdx/docs/overview/kits/page.mdx)，安装文档参考 installation/page.mdx/docs/overview/installation/page.mdx)。

新手建议：直接选 Full Kit，页面全、改起来直观，跑通后再删掉不需要的模块。

二、第 1 步：准备运行环境（Node.js 22 + pnpm）

Shadboard 的 package.json 中声明了版本要求，开始前请确认：

1. Node.js 22 及以上：从 Node.js 官网下载安装 LTS 版本即可；
2. pnpm 10 及以上（项目推荐的包管理器）；
3. 代码编辑器：推荐 VSCode。

在终端中执行以下命令，一行命令安装 pnpm 并验证版本：

npm install -g pnpm # 全局安装 pnpm node -v # 确认 >= v22 pnpm --version # 确认 >= 10

💡 版本不满足时请先升级 Node.js，否则安装依赖阶段可能报错。

三、第 2 步：获取项目源码并安装依赖

3.1 克隆 Shadboard 仓库

git clone https://gitcode.com/gh_mirrors/sh/shadboard cd shadboard

3.2 进入 Full Kit 并安装依赖

cd full-kit pnpm install

安装过程中会自动执行postinstall脚本（即prisma generate，初始化 prisma/schema.prisma 客户端），并复用仓库自带的 SQLite 数据库文件 dev.db，因此无需手动配置数据库，等待终端出现完成提示即可。

3.3 配置环境变量（Full Kit 必做）

Full Kit 内置了 NextAuth 登录认证（见 next-auth.ts），需要复制一份环境变量文件：

cp .env.example .env

然后打开.env，把NEXTAUTH_SECRET替换为任意随机字符串（如openssl rand -hex 32的输出），其余默认值（http://localhost:3000等）保持不动即可。各字段含义可参考 .env.example。

📌 Starter Kit 用户可跳过此步，直接在starter-kit/目录执行pnpm install即可。

四、第 3 步：一键启动，预览你的后台面板

在full-kit/目录下启动开发服务器：

pnpm run dev

看到Ready提示后，打开浏览器访问http://localhost:3000，就会看到熟悉的登录页；用内置演示账号登录后，会跳转到默认首页Analytics 仪表盘（路径/dashboards/analytics，由HOME_PATHNAME控制）。

至此，一个完整的 Shadboard 管理后台已在本地跑起来了 ✅ 试试右下角的设置按钮，可以体验亮/深色模式和配色切换。

五、常见问题快速解决

❓ 提示 3000 端口被占用？加参数换端口启动即可：

pnpm run dev -- --port 3001

❓ 安装后登录报错、提示 Prisma 相关问题？手动重新生成 Prisma 客户端并同步数据库：

pnpm exec prisma generate pnpm migrate

❓ 能用 npm 或 yarn 代替 pnpm 吗？可以（npm run dev同样有效），但项目锁文件为 pnpm-lock.yaml，使用 pnpm 能保证依赖版本完全一致，推荐优先使用。

六、下一步：开始定制你的后台

跑通之后，几个值得先逛的目录：

• 仪表盘页面：full-kit/src/app/[lang]/(dashboard-layout)/dashboards/
• 可复用 UI 组件库：full-kit/src/components/ui/
• 侧边栏导航配置：full-kit/src/data/navigations.ts
• 用户演示数据：full-kit/src/data/user.ts

Shadboard 采用 MIT 协议免费开源，欢迎在 README.md 中了解完整特性列表，并按照 CONTRIBUTING.md 的贡献指南为社区提交你的第一个 PR。祝搭建顺利，早日拥有自己的专属管理后台！🎉