Naive Ui Admin

Appearance

Return to top
On this page

开始

本文会帮助你从头启动项目

前言

关于组件

项目虽然二次封装了一些组件，但是可能不能满足大部分的要求。所以，如果组件不满足你的要求，完全可以不用甚至删除代码自己写，不必坚持使用项目自带的组件。

环境准备

本地环境需要安装 Node.js 和 Git，推荐使用 pnpm 进行依赖安装

注意

  • Node.js 版本要求 >= 20.19.0
  • 包管理器要求 pnpm >= 10

工具配置

如果您使用的 IDE 是vscode(推荐)的话，可以安装以下工具来提高开发效率及代码格式化

代码获取

注意

注意存放代码的目录及所有父级目录不能存在中文、韩文、日文以及空格，否则安装依赖后启动会出错。

从 GitHub 获取代码

bash
# clone 代码
git clone https://github.com/jekip/naive-ui-admin.git

从 Gitee 获取代码

如果从 github clone 代码较慢的话，可以尝试用 Gitee 同步代码到自己的仓库，再 clone 下来即可。

也可以通过下方地址进行 clone

bash
git clone https://gitee.com/Ahjung/naive-ui-admin.git

注意

Gitee的代码可能不是最新的

安装

安装 Node.js

如果您电脑未安装Node.js，请安装它。

验证

bash
# 出现相应npm版本即可
npm -v
# 出现相应node版本即可
node -v

如果你需要同时存在多个 node 版本，可以使用 Nvm 或者其他工具进行 Node.js 进行版本管理。

安装依赖

pnpm 安装

如果未安装pnpm，可以用下面命令来进行全局安装

bash
# 全局安装pnpm
npm i -g pnpm
# 验证
pnpm -v # 出现对应版本号即代表安装成功

依赖安装命令

在项目根目录下，打开命令窗口执行，耐心等待安装完成即可

bash
# 安装依赖
pnpm install

npm script

bash
"scripts": {
  # 安装依赖
  "bootstrap": "pnpm install",
  # 运行项目（serve 为历史别名）
  "serve": "pnpm run dev",
  "dev": "vite",
  # 构建项目（构建后自动输出首屏体积报告）
  "build": "vite build && esno ./build/script/postBuild.ts && pnpm run size",
  # 清空缓存后构建项目
  "build:no-cache": "pnpm clean:cache && pnpm run build",
  # 只统计首屏静态闭包体积（gzip / brotli）
  "size": "node scripts/report-bundle-size.mjs dist",
  # 生成 rollup-plugin-visualizer 报告到 .analyze/ 并统计体积
  "report": "cross-env ANALYZE=true vite build && pnpm run size",
  # 预览打包后的内容（先打包再进行预览）
  "preview": "pnpm run build && vite preview",
  # 直接预览本地 dist 文件目录
  "preview:dist": "vite preview",
  # 删除缓存
  "clean:cache": "rimraf node_modules/.cache/ && rimraf node_modules/.vite",
  # 删除 node_modules (Windows 系统手动删除较慢，可用该命令)
  "clean:lib": "rimraf node_modules",
  # 类型检查（只读）
  "type-check": "vue-tsc --noEmit",
  # ESLint（自动修复）
  "lint:eslint": "eslint \"{src,mock,build}/**/*.{vue,ts,tsx}\" --fix",
  # Prettier 格式化（会对 src 下所有代码格式化，请谨慎执行）
  "lint:prettier": "prettier --write --log-level warn \"src/**/*.{js,json,tsx,css,less,scss,vue,html,md}\"",
  # Stylelint（自动修复）
  "lint:stylelint": "stylelint --fix \"**/*.{vue,less,postcss,css,scss}\" --cache --cache-location node_modules/.cache/stylelint/",
  # 交互式提交（cz-customizable）
  "commit": "git-cz",
  "prepare": "husky",
},

体积预算

pnpm build 结束时会校验首屏 gzip 体积，默认预算 500KB；可通过 BUNDLE_BUDGET_KB 环境变量覆盖。

接下来你可以修改代码进行业务开发了。我们内建了模拟数据、HMR 实时预览、状态管理、国际化、全局路由等各种实用的功能辅助开发，请阅读其他章节了解更多。

目录说明

bash

.
├── build # 打包脚本相关
│   ├── script # 构建后置脚本
│   └── vite # vite 配置（plugin / proxy）
├── mock # mock 数据
├── public # 公共静态资源目录
├── scripts # 体积统计等独立脚本
├── src # 主目录
│   ├── api # 接口文件
│   ├── assets # 资源文件
│   ├── components # 公共组件
│   ├── config # 站点配置
│   ├── directives # 指令
│   ├── enums # 枚举/常量
│   ├── hooks # hook
│   ├── layout # 布局
│   ├── locales # 多语言（lang/zh-CN、lang/en-US）
│   ├── main.ts # 主入口
│   ├── plugins # 插件（naiveDiscreteApi 等）
│   ├── router # 路由配置（modules 下自动注册）
│   ├── settings # 项目配置
│   │   ├── animateSetting.ts # 路由动画配置
│   │   ├── componentSetting.ts # 组件配置
│   │   ├── designSetting.ts # 样式配置
│   │   └── projectSetting.ts # 项目配置
│   ├── store # 数据仓库（Pinia）
│   ├── utils # 工具类
│   └── views # 页面
├── types # 全局类型声明
├── vite.config.mts # vite 配置文件
└── tailwind.config.js # Tailwind CSS 配置