## File: README.md

[](https://sonarcloud.io/summary/new_code?id=vbenjs_vue-vben-admin) [](https://github.com/vbenjs/vue-vben-admin/actions/workflows/codeql.yml) [](https://github.com/vbenjs/vue-vben-admin/actions/workflows/build.yml) [](https://github.com/vbenjs/vue-vben-admin/actions/workflows/ci.yml) [](https://github.com/vbenjs/vue-vben-admin/actions/workflows/deploy.yml)

**English** | [中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md)

## Introduction

Vue Vben Admin is a free and open source middle and back-end template. Using the latest `vue3`, `vite`, `TypeScript` and other mainstream technology development, the out-of-the-box middle and back-end front-end solutions can also be used for learning reference.

## Upgrade Notice

This is the latest version, 5.0, and it is not compatible with previous versions. If you are starting a new project, it is recommended to use the latest version. If you wish to view the old version, please use the [v2 branch](https://github.com/vbenjs/vue-vben-admin/tree/v2).

## Features

- **Latest Technology Stack**: Developed with cutting-edge front-end technologies like Vue 3 and Vite
- **TypeScript**: A language for application-scale JavaScript
- **Themes**: Multiple theme colors available with customizable options
- **Internationalization**: Comprehensive built-in internationalization support
- **Permissions**: Built-in solution for dynamic route-based permission generation

## Preview

- [Vben Admin](https://vben.pro/) - Full version Chinese site

Test Account: vben/123456



### Use Gitpod

Open the project in Gitpod (free online dev environment for GitHub) and start coding immediately.

[](https://gitpod.io/#https://github.com/vbenjs/vue-vben-admin)

## Documentation

[Document](https://doc.vben.pro/)

## Install and Use

1. Get the project code

```bash
git clone https://github.com/vbenjs/vue-vben-admin.git
```

2. Install dependencies

```bash
cd vue-vben-admin
npm i corepack
pnpm install
```

3. Run

```bash
pnpm dev
```

4. Build

```bash
pnpm build
```

## Change Log

[CHANGELOG](https://github.com/vbenjs/vue-vben-admin/releases)

## How to Contribute

You are very welcome to join! [Raise an issue](https://github.com/anncwb/vue-vben-admin/issues/new/choose) or submit a Pull Request.

**Pull Request Process:**

1. Fork the code
2. Create your branch: `git checkout -b feat/xxxx`
3. Submit your changes: `git commit -am 'feat(function): add xxxxx'`
4. Push your branch: `git push origin feat/xxxx`
5. Submit `pull request`

## Git Contribution Submission Specification

Reference [vue](https://github.com/vuejs/vue/blob/dev/.github/COMMIT_CONVENTION.md) specification ([Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular))

- `feat` Add new features
- `fix` Fix the problem/BUG
- `style` The code style is related and does not affect the running result
- `perf` Optimization/performance improvement
- `refactor` Refactor
- `revert` Undo edit
- `test` Test related
- `docs` Documentation/notes
- `chore` Dependency update/scaffolding configuration modification etc.
- `ci` Continuous integration
- `types` Type definition file changes

## Browser Support

Tailwind CSS v4.0 is designed for Safari 16.4+, Chrome 111+, and Firefox 128+

Support modern browsers, not IE

| [](http://godban.github.io/browsers-support-badges/)Edge | [](http://godban.github.io/browsers-support-badges/)Firefox | [](http://godban.github.io/browsers-support-badges/)Chrome | [](http://godban.github.io/browsers-support-badges/)Safari |
| :-: | :-: | :-: | :-: |
| last 2 versions | last 2 versions | last 2 versions | last 2 versions |

## Maintainer

[@Vben](https://github.com/anncwb)

## Star History

[](https://star-history.dera.page/#vbenjs/vue-vben-admin&Date)

## Donate

If you think this project is helpful to you, you can help the author buy a cup of coffee to show your support!



<a style="display: block;width: 100px;height: 50px;line-height: 50px; color: #fff;text-align: center; background: #408aee;border-radius: 4px;" href="https://www.paypal.com/paypalme/cvvben">Paypal Me</a>

## Contributors

<a href="https://openomy.app/github/vbenjs/vue-vben-admin" target="_blank" style="display: block; width: 100%;" align="center">
  
 </a>

<a href="https://github.com/vbenjs/vue-vben-admin/graphs/contributors">
  
</a>

## Discord

- [Github Discussions](https://github.com/anncwb/vue-vben-admin/discussions)

## License

[MIT © Vben-2020](./LICENSE)

---

## File: apps/backend-mock/README.md

# @vben/backend-mock

## Description

Vben Admin 数据 mock 服务，没有对接任何的数据库，所有数据都是模拟的，用于前端开发时提供数据支持。线上环境不再提供 mock 集成，可自行部署服务或者对接真实数据，由于 `mock.js` 等工具有一些限制，比如上传文件不行、无法模拟复杂的逻辑等，所以这里使用了真实的后端服务来实现。唯一麻烦的是本地需要同时启动后端服务和前端服务，但是这样可以更好的模拟真实环境。该服务不需要手动启动，已经集成在 vite 插件内，随应用一起启用。

## Running the app

```bash
# development
$ pnpm run start

# production mode
$ pnpm run build
```

---

## File: docs/src/guide/project/changeset.md

# Changeset

项目内置了 [changeset](https://github.com/changesets/changesets) 作为版本管理工具。Changeset 是一个版本管理工具，它可以帮助我们更好的管理版本，生成 changelog，以及自动发布。

详细使用方式可查看官方文档，这里不再阐述。如果你不需要它，可以直接忽略。

## 命令行

changeset 命令在项目中已经内置：

### 交互式填写变更集

```bash
pnpm run changeset
```

### 统一提升版本号

```bash
pnpm run version
```

---

## File: docs/src/guide/project/cli.md

---
outline: deep
---

# CLI

项目中，提供了一些命令行工具，用于一些常用的操作，代码位于 `scrips` 内。

## vsh

用于一些项目操作，如清理项目、检查项目等。

### 用法

```bash
pnpm vsh [command] [options]
```

### vsh check-circular

检查整个项目循环引用，如果有循环引用，会在控制台输出循环引用的模块。

#### 用法

```bash
pnpm vsh check-circular
```

#### 选项

| 选项       | 说明                                |
| ---------- | ----------------------------------- |
| `--staged` | 只检查git暂存区内的文件,默认`false` |

### vsh check-dep

检查整个项目依赖情况，并在控制台输出`未使用的依赖`、`未安装的依赖`信息

#### 用法

```bash
pnpm vsh check-dep
```

#### 选项

| 选项             | 说明                                    |
| ---------------- | --------------------------------------- |
| `-r,--recursive` | 递归删除整个项目,默认`true`             |
| `--del-lock`     | 是否删除`pnpm-lock.yaml`文件,默认`true` |

### vsh lint

对项目进行lint检查，检查项目中的代码是否符合规范。

#### 用法

```bash
pnpm vsh lint
```

#### 选项

| 选项       | 说明                           |
| ---------- | ------------------------------ |
| `--format` | 检查并尝试修复错误,默认`false` |

### vsh publint

对 `Monorepo` 项目进行包规范检查，检查项目中的包是否符合规范。

#### 用法

```bash
pnpm vsh publint
```

#### 选项

| 选项      | 说明                   |
| --------- | ---------------------- |
| `--check` | 仅执行检查,默认`false` |

### vsh code-workspace

生成 `vben-admin.code-workspace` 文件，目前不需要手动执行，会在代码提交时自动执行。

#### 用法

```bash
pnpm vsh code-workspace
```

#### 选项

| 选项            | 说明                                   |
| --------------- | -------------------------------------- |
| `--auto-commit` | `git commit`时候，自动提交,默认`false` |
| `--spaces`      | 缩进格式,默认 `2`个缩进                |

## turbo-run

用于快速执行大仓中脚本，并提供选项式交互选择。

### 用法

```bash
pnpm turbo-run [command]
```

### turbo-run dev

快速执行`dev`命令，并提供选项式交互选择。

---

## File: docs/src/guide/project/dir.md

# 目录说明

目录使用 Monorepo 管理，项目结构如下：

```
/* Detailed source-code truncated for AI context efficiency. */
```

---

## File: docs/src/guide/project/standard.md

# 规范

::: tip 贡献代码

- 如果你想向项目贡献代码，请确保你的代码符合项目的代码规范。
- 如果你使用的是 `vscode`，需要安装以下插件：
  - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查
  - [Oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - Oxlint / Oxfmt 集成
  - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查
  - [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS 格式检查

:::

## 作用

具备基本工程素养的同学都会注重编码规范，而代码风格检查（Code Linting，简称 Lint）是保障代码规范一致性的重要手段。

遵循相应的代码规范有以下好处：

- 较少 bug 错误率
- 高效的开发效率
- 更高的可读性

## 工具

项目的配置文件位于 `internal/lint-configs` 下，你可以在这里修改各种 lint 的配置。

项目内集成了以下几种代码校验工具：

- [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) 用于代码格式化
- [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) 用于 JavaScript / TypeScript 代码检查
- [ESLint](https://eslint.org/) 用于 Vue、JSONC、YAML 等规则检查
- [Stylelint](https://stylelint.io/) 用于 CSS 样式检查
- [Commitlint](https://commitlint.js.org/) 用于检查 git 提交信息的规范
- [Publint](https://publint.dev/) 用于检查 npm 包的规范
- [Cspell](https://cspell.org/) 用于检查拼写错误
- [lefthook](https://github.com/evilmartians/lefthook) 用于管理 Git hooks，在提交前自动运行代码校验和格式化

## Oxfmt

Oxfmt 用于统一项目代码风格，统一缩进、引号、尾逗号等格式。

### 命令

```bash
pnpm oxfmt
pnpm oxfmt --check
```

### 配置

Oxfmt 的根目录入口文件为 `oxfmt.config.ts`，其核心配置位于 `internal/lint-configs/oxfmt-config` 目录下，可以根据项目需求进行修改。

## Oxlint

Oxlint 是当前仓库的主要脚本 lint 工具，用于识别和报告 JavaScript / TypeScript 代码中的问题。

### 命令

```bash
pnpm oxlint
pnpm oxlint --fix
```

### 配置

Oxlint 的核心配置位于 `internal/lint-configs/oxlint-config` 目录下，根目录入口文件为 `oxlint.config.ts`。

## ESLint

ESLint 用于补充 Vue、JSONC、YAML 等规则检查。

### 命令

```bash
pnpm eslint . --cache
```

### 配置

ESLint 配置文件为 `eslint.config.mjs`，其核心配置放在 `internal/lint-configs/eslint-config` 目录下，可以根据项目需求进行修改。

## Stylelint

Stylelint 用于校验项目内部 CSS 的风格，加上编辑器的自动修复，可以很好的统一项目内部 CSS 风格。

### 命令

```bash
pnpm stylelint "**/*.{vue,css,less,scss}" --cache
```

### 配置

Stylelint 配置文件为 `stylelint.config.mjs`，其核心配置放在 `internal/lint-configs/stylelint-config` 目录下，可以根据项目需求进行修改。

## CommitLint

在一个团队中，每个人的 git 的 commit 信息都不一样，五花八门，没有一个机制很难保证规范化，如何才能规范化呢？可能你想到的是 git 的 hook 机制，去写 shell 脚本去实现。这当然可以，其实 JavaScript 有一个很好的工具可以实现这个模板，它就是 commitlint（用于校验 git 提交信息规范）。

### 配置

CommitLint 配置文件为 `.commitlintrc.js`，其核心配置放在 `internal/lint-configs/commitlint-config` 目录下，可以根据项目需求进行修改。

### Git 提交规范

参考 [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular)

- `feat` 增加新功能
- `fix` 修复问题 / BUG
- `style` 代码风格相关无影响运行结果的
- `perf` 优化 / 性能提升
- `refactor` 重构
- `revert` 撤销修改
- `test` 测试相关
- `docs` 文档 / 注释
- `chore` 依赖更新 / 脚手架配置修改等
- `workflow` 工作流改进
- `ci` 持续集成
- `types` 类型修改

### 关闭 Git 提交规范检查

如果你想关闭 Git 提交规范检查，有两种方式：

::: code-group

```bash [临时关闭]
git commit -m 'feat: add home page' --no-verify
```

```yaml [长期关闭]
commit-msg:
  commands:
    # commitlint:
    #   run: pnpm exec commitlint --edit $1
```

:::

如果修改了 `lefthook.yml`，请重新执行：

```bash
pnpm exec lefthook install
```

## Publint

Publint 是一个用于检查 npm 包规范的工具，可以检查包的版本号、导出方式以及 ESM 包结构等问题。

### 命令

```bash
pnpm publint
```

## Cspell

Cspell 是一个用于检查拼写错误的工具，可以检查代码中的拼写错误，避免因为拼写错误导致的 bug。

### 命令

```bash
pnpm check:cspell
```

### 配置

cspell 配置文件为 `cspell.json`，可以根据项目需求进行修改。

## Git Hook

git hook 一般结合各种 lint，在 git 提交代码的时候进行代码风格校验，如果校验没通过，则不会进行提交。需要开发者自行修改后再次进行提交。

### lefthook

有一个问题就是校验会校验全部代码，但是我们只想校验我们自己提交的代码，这个时候就可以使用 lefthook。

最有效的解决方案就是将 lint 校验放到本地，常见做法是使用 lefthook 在本地提交之前先做一次 lint 校验。

项目在 `lefthook.yml` 内部定义了相应的 hooks：

- `pre-commit`: 在提交前运行，用于代码格式化和检查
  - `code-workspace`: 更新 VSCode 工作区配置
  - `lint-md`: 格式化 Markdown 文件
  - `lint-vue`: 格式化并检查 Vue 文件
  - `lint-js`: 格式化并检查 JavaScript / TypeScript 文件
  - `lint-style`: 格式化并检查样式文件
  - `lint-package`: 格式化 `package.json`
  - `lint-json`: 格式化其他 JSON 文件
- `post-merge`: 在合并后运行，用于自动安装依赖
  - `install`: 运行 `pnpm install` 安装新依赖
- `commit-msg`: 在提交时运行，用于检查提交信息格式
  - `commitlint`: 使用 commitlint 检查提交信息

当前 hooks 可通过以下命令安装：

```bash
pnpm exec lefthook install
```

#### 如何关闭 lefthook

如果你想临时关闭 lefthook，可以使用：

```bash
git commit -m 'feat: add home page' --no-verify
```

#### 如何修改 lefthook 配置

如果你想修改 lefthook 的配置，可以编辑 `lefthook.yml` 文件。例如：

```yaml
pre-commit:
  parallel: true
  commands:
    lint-js:
      run: pnpm oxfmt {staged_files} && pnpm oxlint --fix {staged_files} && pnpm eslint --cache --fix {staged_files}
      glob: '*.{js,jsx,ts,tsx}'
```

其中：

- `parallel`: 是否并行执行任务
- `commands`: 定义要执行的任务列表
- `run`: 要执行的命令
- `glob`: 匹配的文件模式
- `{staged_files}`: 表示暂存的文件列表

---

## File: docs/src/guide/project/tailwindcss.md

# Tailwind CSS

[Tailwind CSS](https://tailwindcss.com/) 是一个实用性优先的 CSS 框架，用于快速构建自定义设计。当前项目使用的是 **Tailwind CSS v4**。

## 配置

项目当前不再通过 `tailwind.config.*` 文件维护 Tailwind 配置，主题与扫描范围都统一放在 CSS 与共享 Vite 配置中。

- 主题入口：`internal/tailwind-config/src/theme.css`
- Vite 集成：`internal/vite-config`

在 `global.css` 中你会看到当前项目使用的 Tailwind CSS v4 指令，例如：

- `@source`
- `@custom-variant`
- `@theme`
- `@theme inline`
- `@utility`

## 包使用 Tailwind CSS 的方式

当前项目不会根据某个包下是否存在 `tailwind.config.mjs` 来决定是否启用 Tailwind CSS。

应用和包统一复用 `@vben/vite-config`，并由该配置接入 `@tailwindcss/vite`。Tailwind 的扫描范围则统一在 `@vben/tailwind-config` 对应的 `internal/tailwind-config/src/theme.css` 中维护。

::: tip 包使用 Tailwind CSS 的说明

如果你是纯粹的 SDK 包，不需要使用 Tailwind CSS，则无需额外增加旧版 `tailwind.config.*` 文件。

:::

## Vue SFC 中的 `@apply`

项目对 Vue 单文件组件中的 `@apply` 做了统一处理，相关逻辑位于：

- `internal/vite-config/src/plugins/tailwind-reference.ts`

当组件样式中使用 `@apply` 时，会自动注入 `@reference "@vben/tailwind-config/theme"`，一般不需要手动补充。