基于 Vben Admin 框架的 Vue 3 前端项目配置文件及常用命令

一个基于 Vben Admin 框架的 Vue 3 前端项目，使用了 pnpm 作为包管理器，并采用了 monorepo（单仓库多项目管理）的结构。

1. 项目配置文件 (根目录)

.commitlintrc.js
- 作用: 用于规范 Git 提交信息（commit message）的格式。
- 细节 : 它直接导出了 @vben/commitlint-config，这个配置集成了流行的 @commitlint/config-conventional（约定式提交规范），例如 feat:, fix:, docs: 等。这能确保团队提交历史的清晰和一致性。
.gitpod.yml
- 作用: Gitpod 是一个在线 IDE 环境（云端开发环境）。此文件是 Gitpod 的配置文件。
- 细节 : 它告诉 Gitpod 在启动工作区时，将 5555 端口设为预览端口，并执行 pnpm install 和 pnpm run dev:play（运行一个开发示例）来初始化项目。
cspell.json
- 作用 : 配置 cspell（一个拼写检查工具）。
- 细节 : 它定义了一组 words（自定义词汇，如 vben, yudao, axios），以防止拼写检查器将它们误报为错误。同时，它还设置了 ignorePaths，忽略 dist、node_modules 等构建和依赖目录，避免检查这些非源码文件。
eslint.config.mjs
- 作用 : ESLint 的配置文件（使用新的扁平配置格式）。
- 细节 : 它从 @vben/eslint-config 导入并导出一个默认配置。ESLint 是用于检查 JavaScript/TypeScript 代码语法和风格错误的重要工具，此文件统一了团队代码风格。
lefthook.yml
- 作用 : Git Hooks （Git 钩子）管理工具，用于在 Git 操作的特定节点（如 pre-commit、commit-msg）执行自动化脚本。
- 细节 :
  - pre-commit（提交前） : 会对暂存的文件（{staged_files}）并行或串行执行 oxlint（快速 Lint）、oxfmt（格式化）、eslint（修复）、stylelint（修复 CSS）和 pnpm check:type（TypeScript 类型检查）。目的是确保提交的代码质量。
  - post-merge（合并后） : 执行 pnpm install，确保合并代码后依赖是最新的。
  - commit-msg（提交信息） : 执行 commitlint，验证提交信息是否符合规范。
oxfmt.config.ts
- 作用 : oxfmt（一个基于 Rust 的极速代码格式化工具）的配置文件。
- 细节 : 配置了需要忽略格式化的文件/目录模式（如 dist、node_modules、*.svg 等）。
oxlint.config.ts
- 作用 : oxlint（一个基于 Rust 的极速 Lint 工具）的配置文件。
- 细节 : 导入了 @vben/oxlint-config 并将其传递给 defineConfig。oxlint 旨在作为 ESLint 的补充或替代，提供更快的检查速度。
package.json
- 作用 : 这是 Node.js 项目的核心配置文件。
- 细节 :
  - 定义了项目名称（vben-admin-monorepo）、版本、作者和许可证。
  - 包含了大量 scripts（脚本），如 dev（开发）、build（构建）、lint（代码检查）、check:type（类型检查）等，这些都是日常开发的入口。
  - 列出了 devDependencies（开发依赖），如 eslint、typescript、vite、turbo 等。
  - 明确了 engines（引擎）要求，强制使用 node >= v22.18.0 和 pnpm >= 11.0.0。
pnpm-lock.yaml
- 作用 : pnpm 的锁定文件。
- 细节: 它精确锁定了项目依赖的每个包的具体版本和哈希值，确保团队所有成员和 CI/CD 环境安装的依赖版本完全一致，是保证项目可复现构建的关键。文件内容非常大，包含了海量的依赖关系。
pnpm-workspace.yaml
- 作用 : 定义了 pnpm workspace（工作空间）。
- 细节 : 它告诉 pnpm，apps/*、internal/*、packages/* 等目录都是独立的子项目（包）。这是实现 monorepo 的基础。它还配置了 catalog（目录），用于统一管理所有子项目中的依赖版本。
stylelint.config.mjs
- 作用 : Stylelint 的配置文件。
- 细节 : 继承并导出了 @vben/stylelint-config。Stylelint is a tool for checking the code quality and style of CSS/SCSS/Less and other style files.
tea.yaml
- 作用 : 与 Tea Protocol（一个去中心化的开源软件资助协议）相关的文件。
- 细节: 用于将项目注册到 Tea 协议，并指定代码所有者。对项目本身的运行没有影响。
turbo.json
- 作用 : Turbo 的配置文件。Turbo 是一个用于 monorepo 项目的高性能构建系统。
- 细节 : 它定义了各个任务（tasks）的依赖关系（dependsOn）、输出目录（outputs）和缓存策略。例如，build 任务会依赖其他包的 build 任务先完成，并缓存 dist 目录。
vitest.config.ts
- 作用 : Vitest 的配置文件。Vitest 是一个由 Vite 驱动的极速单元测试框架。
- 细节 : 它配置了测试运行环境为 happy-dom（一个轻量级的浏览器 DOM 模拟环境），并设置了一些排除测试的目录。

1. app目录

.env.development

env 复制代码

VITE_PORT=5999

只作用于 本地开发 npm run dev ，控制 vite‑dev 开发服务器监听端口，本地跑前端服务，浏览器访问 http://localhost:5999。
这个端口是 Vite开发服务器（devServer）端口 ，仅开发阶段有效。
.env.production
一般不写 VITE_PORT
npm run build 生产打包的时候，VITE_PORT 这个变量完全无效，被忽略。
build 输出的是静态 dist 文件，打包产物本身没有端口概念。

生产环境：dist 是静态资源，由 Nginx / Caddy 这类 web server 托管，端口由 Nginx（80/443）决定，不由 vite 控制。

总结

这些配置文件共同构成了一套现代化且工业化的前端工程化体系：

Monorepo 管理 : 通过 pnpm-workspace.yaml 和 turbo.json 高效管理多包项目。
代码质量 : 通过 lefthook.yml 在 Git 提交前，强制运行 eslint, stylelint, oxlint 和 TypeScript 类型检查，并使用 commitlint 规范提交信息。
开发效率 : 使用 oxfmt 和 oxlint 等 Rust 工具来加速格式化与检查，使用 cspell 避免拼写错误。
环境统一 : 通过 package.json 的 engines 字段和 pnpm-lock.yaml 锁定了 Node 版本和依赖版本。
云端开发 : 通过 .gitpod.yml 支持一键启动在线开发环境。
项目文档 : README.md 提供了极其详尽的项目介绍和功能列表。

npm install -g pnpm@11.7.0 # ✅ 全局安装 pnpm 11.7.0
pnpm config set registry https://registry.npmmirror.com/ # ✅ 设置镜像源
pnpm -v # ✅ 查看 pnpm 版本
pnpm install # ✅ 安装项目依赖
pnpm run build:demo-app #