本地开发 ​

前置准备 ​

为了更好的开发体验，我们提供了一些工具配置、项目说明，以便于您更好的开发。

需要掌握的基础知识 ​

本项目需要一定前端基础知识，请确保掌握 Vue 的基础知识，以便能处理一些常见的问题。建议在开发前先学一下以下内容，提前了解和学习这些知识，会对项目理解非常有帮助:

工具配置 ​

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

Npm Scripts ​

npm 脚本是项目常见的配置，用于执行一些常见的任务，比如启动项目、打包项目等。以下的脚本都可以在项目根目录的 package.json 文件中找到。

执行方式为：pnpm run [script] 或 npm run [script]。

json
{
  "scripts": {
    // 启动本地开发服务
    "dev": "node scripts/generate-config.mjs && vite",
    // 本地预览打包好的静态项目
    "preview": "vite preview --port 3000",
    // 构建生产环境打包项目
    "build": "node scripts/generate-config.mjs && vite build",
    // 静态 TypeScript 类型安全校验
    "type-check": "vue-tsc --noEmit",
    // 自动格式化排版并修复脚本规则
    "format": "oxfmt --config=./oxfmt.config.mjs --ignore-path=.gitignore --ignore-path=.oxfmtignore --write . && oxlint --config=oxlint.config.mjs --fix .",
    // 一键运行所有的脚本、格式与样式静态分析
    "lint": "pnpm run lint:oxlint && pnpm run lint:fmt && pnpm run lint:style",
    // 检查项目代码格式是否排版正确
    "lint:fmt": "oxfmt --config=./oxfmt.config.mjs --ignore-path=.gitignore --ignore-path=.oxfmtignore --check .",
    // 静态校验代码规范和潜在 Bug 错误
    "lint:oxlint": "oxlint --config=oxlint.config.mjs .",
    // 校验 CSS、SCSS 和 Vue 的样式代码规范
    "lint:style": "stylelint \"**/*.{css,scss,vue}\" --cache",
    // 清理打包产物与预编译临时缓存
    "clean": "node ./scripts/clean.mjs",
    // 启动交互式代码模版生成脚手架
    "plop": "plop",
    // 初始化本地 Git 提交拦截 Hooks 配置
    "prepare": "husky"
  }
}

本地运行项目 ​

如需本地运行文档，并进行调整，可以执行以下命令，执行该命令，你可以选择需要的应用进行开发：

bash
pnpm dev

区分构建环境 ​

在实际的业务开发中，通常会在构建时区分多种环境，如测试环境 test、生产环境 build 等。

此时可以修改三个文件，在其中增加对应的脚本配置来达到区分生产环境的效果。

以添加测试环境 test 为例：

  • my-app/package.json
json
"scripts": {
  "build:prod": "pnpm vite build --mode production",
  "build:test": "pnpm vite build --mode test",
  "build:analyze": "pnpm vite build --mode analyze",
  "dev": "pnpm vite --mode development",
  "preview": "vite preview",
  "typecheck": "vue-tsc --noEmit --skipLibCheck"
},

增加命令 "build:test"，并将原 "build" 改为 "build:prod" 以避免同时构建两个环境的包。

  • package.json
json
"scripts": {
    "build": "cross-env NODE_OPTIONS=--max-old-space-size=8192 turbo build",
    "build:analyze": "turbo build:analyze",
    "build:antd": "pnpm run build --filter=@vben/web-antd",
    "build-test:antd": "pnpm run build --filter=@vben/web-antd build:test",

    ······
}

在根目录 package.json 中加入构建测试环境的命令。

  • turbo.json
json
"tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [
        "dist/**",
        "dist.zip",
        ".vitepress/dist.zip",
        ".vitepress/dist/**"
      ]
    },

    "build-test:antd": {
      "dependsOn": ["@vben/web-antd#build:test"],
      "outputs": ["dist/**"]
    },

    "@vben/web-antd#build:test": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },

    ······

在 turbo.json 中加入相关依赖的命令。

公共静态资源 ​

项目中需要使用到的公共静态资源，如：图片、静态 HTML 等，需要在开发中通过 src="/xxx.png" 直接引入的。

需要将资源放在对应项目的 public/static 目录下。引入的路径为：src="/static/xxx.png"。

问题解决 ​

如果你在使用过程中遇到依赖相关的问题，可以尝试以下重新安装依赖：

bash
# 请在项目根目录下执行
# 该命令会删除整个仓库所有的 node_modules、yarn.lock、package-lock.json 后
# 再进行依赖重新安装（安装速度会明显变慢）。
pnpm reinstall