fe-cli-starter 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# fe-cli-starter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一套开箱即用的前端工程化 CLI 脚手架，帮助中小团队解决**新项目初始化繁琐、代码规范不统一、存量代码整改费时**的问题。
+
+## 解决什么痛点
+- 新项目每次都要重新配 ESLint / Prettier / Stylelint / Commitlint，费时且容易漏
+- 多个项目代码风格不一致，Review 成本高
+- 存量老项目没有规范，想整改却无从下手
+
+## 功能
+1. `create`：交互式初始化 Vue3 + Vite 项目，可选启用 Stylelint
+2. 内置统一规范集：ESLint + Prettier + Stylelint + Commitlint（Git 提交信息校验）
+3. `scan`：扫描存量项目，输出规范问题清单
+4. `fix`：一键批量修复存量代码格式问题
+
+## 安装使用
+```bash
+# 全局安装
+npm install -g fe-cli-starter
+
+# 交互式初始化新项目
+fe create my-project
+
+# 或跳过交互，直接指定选项（适合CI）
+fe create my-project --no-stylelint
+
+# 扫描存量项目规范问题
+fe scan ./my-old-project
+
+# 一键修复
+fe fix ./my-old-project
+```
+
+## 实测输出
+```
+$ fe scan ./demo-app
+▶ 扫描规范问题：./demo-app
+  [格式] 需要格式化: src/messy.js
+
+  src/messy.js
+    1:8   warning  'a' is assigned a value but never used       no-unused-vars
+    4:1   warning  Unexpected console statement                 no-console
+
+✘ 共发现 5 个规范问题，可执行 fe fix ./demo-app 尝试自动修复
+
+$ fe fix ./demo-app
+▶ 一键修复：./demo-app
+  [格式] 已重新格式化 1 个文件
+✘ 仍有 4 个问题无法自动修复，需手动处理
+```
+
+## 内置规范
+| 类别 | 工具 | 说明 |
+| --- | --- | --- |
+| JS 代码 | ESLint | 基于 Vue3 推荐规则扩展（no-console、no-unused-vars 等） |
+| 格式化 | Prettier | 统一缩进、引号、分号等 |
+| 样式 | Stylelint | CSS/SCSS/Less 规则 |
+| 提交 | Commitlint | Git 提交信息格式校验 |
+
+## 生成项目的目录结构
+```
+my-project/
+├── AGENTS.md               # AI 编码助手 / 团队开发约定
+├── README.md               # 项目说明（含项目名）
+├── docs/                   # 项目文档目录（需求/接口/部署）
+├── public/                 # 静态资源目录（构建时原样拷贝）
+├── eslint.config.mjs       # ESLint 配置（ESLint 9 flat config）
+├── stylelint.config.mjs    # 样式规范配置（可选启用）
+├── prettier.config.mjs     # 格式化规则（含注释说明）
+├── .prettierignore
+├── vite.config.js          # 别名 / 代理 / 按需导入 / 分包
+├── index.html
+└── src/
+    ├── main.js             # 挂载 pinia + router
+    ├── App.vue
+    ├── assets/README.md    # 静态资源目录说明（图片/全局样式/字体）
+    ├── components/README.md # 公共组件目录说明（跨页面复用组件）
+    ├── router/index.js     # 路由骨架
+    ├── stores/counter.js   # Pinia store 示例
+    ├── utils/request.js    # axios 封装（token 拦截 / 错误处理）
+    └── views/HomeView.vue  # 示例页面
+```
+
+## 为什么配置文件是 `.mjs` 后缀？
+核心原因：**强制该文件按 ESM（`import/export`）解析，不受目标项目 package.json 的 `"type"` 字段影响。**
+
+| 后缀 | Node 解析方式 |
+| --- | --- |
+| `.js` | 看 package.json 的 `"type"`：有 `"module"` 是 ESM，否则是 CommonJS |
+| `.mjs` | 强制按 ESM 解析，任何项目通用 |
+| `.cjs` | 强制按 CommonJS 解析 |
+
+具体到本脚手架：
+1. **ESLint 9 已废弃 `.eslintrc.*` 旧格式**，新版 flat config 官方推荐文件名就是 `eslint.config.mjs`；旧 JSON 格式不支持 `import` 插件、不能写注释，表达不了 flat config 的写法
+2. `.mjs` 保证配置在**任何项目里都能正确运行**：新项目（`"type": "module"`）没问题；老项目没有 `"type": "module"` 时，`.js` 会被按 CommonJS 解析，`import` 语法直接报错 `Cannot use import statement outside a module`——用 `.mjs` 就规避了这个坑。这对 `fe fix` 整改存量项目尤其重要
+3. `vite.config.js` 因为生成项目固定带 `"type": "module"`，用 `.js` 即可；Vite 同样支持 `.mjs`
+
+## 与 `npm create vue` 官方脚手架的区别
+官方模板解决"项目怎么跑起来"；本工具解决"团队项目怎么统一规范、老项目怎么低成本整改"。核心价值在**规范集统一 + 存量项目扫描修复**，并预置团队全家桶：vue-router、pinia、element-plus（按需自动导入）、axios 封装、dayjs、echarts（独立分包）、@vueuse/core、lodash-es、sass。
+
+## 适合谁用
+- 2~20人的前端团队，想统一项目规范
+- 经常新起项目，希望初始化即规范
+- 手上有老项目需要做规范整改
+
+## 技术实现
+- Node.js + Commander：命令注册
+- Inquirer：交互式问答
+- EJS：项目模板渲染
+- 产物支持对存量项目的扫描与批量修复
+
+> 注：本项目为个人开源演示实现，可按团队需求定制扩展。
+
+## License
+MIT

package/bin/fe.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { create } from '../commands/create.js';
+import { scan, fix } from '../commands/index.js';
+
+program.name('fe').description('前端工程化脚手架：初始化项目 / 扫描规范问题 / 一键修复').version('1.0.0');
+
+program
+  .command('create <name>')
+  .description('交互式初始化一个 Vue3 + Vite 项目')
+  .option('--no-stylelint', '不启用 Stylelint')
+  .action((name, opts) => create(name, { useStylelint: opts.stylelint }));
+
+program
+  .command('scan [dir]')
+  .description('扫描存量项目的规范问题（默认当前目录）')
+  .action(scan);
+
+program
+  .command('fix [dir]')
+  .description('一键修复存量代码格式问题（默认当前目录）')
+  .action(fix);
+
+program.parse(process.argv);

package/commands/create.js

@@ -0,0 +1,62 @@
+import { confirm } from '@inquirer/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ejs from 'ejs';
+
+const TEMPLATE_DIR = fileURLToPath(new URL('../templates/vue3-vite/', import.meta.url));
+const CONFIG_DIR = fileURLToPath(new URL('../config/', import.meta.url));
+
+export async function create(name, preset = {}) {
+  const targetDir = path.resolve(process.cwd(), name);
+  if (fs.existsSync(targetDir)) {
+    console.error(`✘ 目录已存在：${targetDir}`);
+    process.exit(1);
+  }
+
+  const useStylelint =
+    preset.useStylelint ?? (await confirm({ message: '是否启用 Stylelint（样式规范）？', default: true }));
+
+  console.log(`\n▶ 正在生成项目 ${name} ...`);
+
+  // 1. 渲染并拷贝模板文件（递归）
+  renderDir(TEMPLATE_DIR, targetDir, { projectName: name, useStylelint });
+
+  // 2. 拷贝规范配置（按选项）
+  copyIf(path.join(CONFIG_DIR, 'eslint.config.mjs'), targetDir);
+  copyIf(path.join(CONFIG_DIR, 'prettier.config.mjs'), targetDir);
+  copyIf(path.join(CONFIG_DIR, '.prettierignore'), targetDir);
+  if (useStylelint) {
+    copyIf(path.join(CONFIG_DIR, 'stylelint.config.mjs'), targetDir);
+    copyIf(path.join(CONFIG_DIR, '.stylelintignore'), targetDir);
+  }
+
+  console.log(`✔ 项目已生成：${targetDir}\n`);
+  console.log('下一步：');
+  console.log(`  cd ${name}`);
+  console.log('  npm install');
+  console.log('  npm run dev');
+}
+
+function renderDir(srcDir, destDir, data) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      renderDir(src, dest, data);
+    } else if (entry.name.endsWith('.ejs')) {
+      const outName = entry.name.replace(/\.ejs$/, '');
+      const dest = path.join(destDir, outName);
+      const tpl = fs.readFileSync(src, 'utf8');
+      fs.writeFileSync(dest, ejs.render(tpl, data));
+    } else {
+      const outName = entry.name.startsWith('_') ? `.${entry.name.slice(1)}` : entry.name;
+      fs.copyFileSync(src, path.join(destDir, outName));
+    }
+  }
+}
+
+function copyIf(src, destDir) {
+  if (fs.existsSync(src)) fs.copyFileSync(src, path.join(destDir, path.basename(src)));
+}

package/commands/index.js

@@ -0,0 +1,29 @@
+import { scanDir } from '../lib/lint.js';
+
+export async function scan(dir = '.') {
+  await runLint(dir, false);
+}
+
+export async function fix(dir = '.') {
+  await runLint(dir, true);
+}
+
+async function runLint(dir, fixMode) {
+  const target = dir ? dir : '.';
+  if (fixMode) {
+    console.log(`▶ 一键修复：${target}`);
+  } else {
+    console.log(`▶ 扫描规范问题：${target}`);
+  }
+  const results = await scanDir(target, fixMode);
+  let total = 0;
+  for (const r of results) {
+    if (r.output) console.log(r.output.trimEnd());
+    total += r.count;
+  }
+  if (fixMode) {
+    console.log(total > 0 ? `\n✘ 仍有 ${total} 个问题无法自动修复，需手动处理` : '\n✔ 修复完成，全部通过');
+  } else {
+    console.log(total > 0 ? `\n✘ 共发现 ${total} 个规范问题，可执行 fe fix ${target} 尝试自动修复` : '\n✔ 未发现规范问题');
+  }
+}

package/config/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.min.*

package/config/.stylelintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/config/eslint.config.mjs

@@ -0,0 +1,21 @@
+import js from '@eslint/js';
+import pluginVue from 'eslint-plugin-vue';
+
+export default [
+  js.configs.recommended,
+  ...pluginVue.configs['flat/recommended'],
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: {
+      'no-console': 'warn',
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      'vue/multi-word-component-names': 'off',
+    },
+  },
+  {
+    ignores: ['node_modules/**', 'dist/**'],
+  },
+];

package/config/prettier.config.mjs

@@ -0,0 +1,14 @@
+export default {
+  // 行尾加分号
+  semi: true,
+  // 使用单引号（JS/TS/Vue）
+  singleQuote: true,
+  // 每行最大宽度 100，超出自动换行
+  printWidth: 100,
+  // 对象/数组最后一项也加逗号，便于 git diff 干净
+  trailingComma: 'all',
+  // 缩进 2 空格
+  tabWidth: 2,
+  // 统一换行符为 LF，避免 Windows/Mac 协作时文件被整体改动
+  endOfLine: 'lf',
+};

package/config/stylelint.config.mjs

@@ -0,0 +1,10 @@
+import stylelintConfigStandard from 'stylelint-config-standard';
+
+export default {
+  extends: [stylelintConfigStandard],
+  rules: {
+    'selector-class-pattern': null,
+    'custom-property-empty-line-before': null,
+  },
+  ignoreFiles: ['node_modules/**', 'dist/**'],
+};

package/lib/lint.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { globSync } from 'glob';
+import * as prettier from 'prettier';
+
+const CONFIG_DIR = path.dirname(fileURLToPath(new URL('../config/eslint.config.mjs', import.meta.url)));
+const IGNORE_PATTERNS = ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/*.min.*'];
+
+export async function scanDir(target, fixMode) {
+  const absTarget = path.resolve(target);
+  const patterns = ['**/*.{js,mjs,ts,vue,jsx,tsx}'];
+
+  const eslint = await import('eslint');
+  const { ESLint } = eslint;
+
+  const results = [];
+
+  // 1. ESLint（格式之外的问题）
+  try {
+    const eslintrc = new ESLint({
+      cwd: absTarget,
+      fix: fixMode,
+      overrideConfigFile: path.join(CONFIG_DIR, 'eslint.config.mjs'),
+      ignore: true,
+    });
+    const lintResults = await eslintrc.lintFiles(patterns);
+    if (fixMode) await ESLint.outputFixes(lintResults);
+    const formatter = await eslintrc.loadFormatter('stylish');
+    const count = lintResults.reduce(
+      (sum, r) => sum + r.errorCount + r.warningCount,
+      0
+    );
+    const formatted = formatter.format(lintResults.filter((r) => r.messages.length));
+    results.push({ count, output: formatted });
+  } catch (e) {
+    results.push({ count: 0, output: `ESLint 扫描跳过：${e.message.split('\n')[0]}\n` });
+  }
+
+  // 2. Prettier 格式检查/修复
+  try {
+    const files = globSync(patterns.map((p) => path.join(absTarget, p)), {
+      ignore: IGNORE_PATTERNS,
+      nodir: true,
+    });
+    let changed = 0;
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf8');
+      const options = await prettier.resolveConfig(file);
+      const formatted = await prettier.format(content, {
+        ...options,
+        filepath: file,
+      });
+      if (formatted !== content) {
+        if (fixMode) {
+          fs.writeFileSync(file, formatted);
+        } else {
+          console.log(`  [格式] 需要格式化: ${path.relative(absTarget, file)}`);
+        }
+        changed++;
+      }
+    }
+    results.push({
+      count: fixMode ? 0 : changed,
+      output: fixMode ? `  [格式] 已重新格式化 ${changed} 个文件\n` : '',
+    });
+  } catch (e) {
+    results.push({ count: 0, output: `Prettier 扫描跳过：${e.message}\n` });
+  }
+
+  return results;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "fe-cli-starter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "开箱即用的前端工程化 CLI 脚手架：初始化 Vue3+Vite 项目、扫描与一键修复存量代码规范问题",
+  "bin": {
+    "fe": "./bin/fe.js"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "commands",
+    "lib",
+    "templates",
+    "config"
+  ],
+  "scripts": {
+    "test": "node bin/fe.js --help"
+  },
+  "keywords": [
+    "cli",
+    "scaffold",
+    "eslint",
+    "prettier",
+    "vue3"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^12.0.0",
+    "ejs": "^3.1.10",
+    "prettier": "^3.3.0",
+    "eslint": "^9.0.0",
+    "stylelint": "^16.0.0",
+    "semver": "^7.6.0",
+    "glob": "^11.0.0",
+    "eslint-plugin-vue": "^9.0.0",
+    "@eslint/js": "^9.0.0"
+  }
+}

package/templates/vue3-vite/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md — AI 编码助手工作约定
+
+本文件供 AI 编码助手（如 Trae、Cursor、Copilot 等）在本项目工作时遵循，也作为团队开发约定的一部分。
+
+## 项目技术栈
+- Vue 3（组合式 API `<script setup>`）+ Vite
+- 状态管理：Pinia（`src/stores/`）
+- 路由：Vue Router（`src/router/`）
+- UI 库：Element Plus（unplugin-vue-components 按需自动注册，无需手动 import 组件）
+- 请求：axios（统一走 `src/utils/request.js`，不要在组件里直接 new axios 实例）
+- 日期：dayjs；图表：echarts；工具：@vueuse/core、lodash-es
+
+## 常用命令
+```bash
+npm run dev      # 本地开发
+npm run build    # 生产构建
+npm run lint     # 代码规范检查并自动修复
+```
+
+## 编码约定
+1. 页面放 `src/views/`，公共组件放 `src/components/`，组合式函数放 `src/composables/`
+2. 路由懒加载：`component: () => import('@/views/Xxx.vue')`
+3. 路径别名统一用 `@/`（指向 `src/`）
+4. 接口请求统一走 `src/utils/request.js`，baseURL 与代理在 `vite.config.js` 中配置
+5. 样式使用 SCSS，组件内样式加 `scoped`
+6. 全局状态放 Pinia store，不要用全局变量传数据
+7. 提交前执行 `npm run lint`，保证代码通过规范检查
+
+## 禁止事项
+- 不要引入与现有依赖功能重复的库（如同时引入 moment 和 dayjs）
+- 不要修改 `eslint.config.mjs` / `prettier.config.mjs` 的规则来迁就不规范代码
+- 不要在代码中硬编码后端地址，统一走环境变量与代理

package/templates/vue3-vite/README.md.ejs

@@ -0,0 +1,31 @@
+# <%= projectName %>
+
+基于 fe-cli-starter 生成的 Vue3 + Vite 项目，内置团队规范与常用全家桶。
+
+## 技术栈
+Vue3 · Vite · Pinia · Vue Router · Element Plus · axios · dayjs · echarts
+
+## 快速开始
+```bash
+npm install
+npm run dev     # 开发：http://localhost:5173
+```
+
+## 常用命令
+| 命令 | 说明 |
+| --- | --- |
+| `npm run dev` | 本地开发 |
+| `npm run build` | 生产构建 |
+| `npm run preview` | 预览构建产物 |
+| `npm run lint` | 代码规范检查并自动修复 |
+
+## 目录结构
+见 [AGENTS.md](./AGENTS.md) 与 [docs/](./docs/)。
+
+## 需要按项目修改的配置
+1. `vite.config.js`：`/api` 代理目标地址
+2. `src/utils/request.js`：请求 baseURL、token 取值方式
+3. `index.html`：页面标题
+
+## 相关文档
+- [docs/开发规范.md](./docs/开发规范.md)

package/templates/vue3-vite/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.local
+.DS_Store

package/templates/vue3-vite/docs/README.md

@@ -0,0 +1,10 @@
+# docs — 项目文档目录
+
+存放本项目的开发文档，建议包含：
+
+- `开发规范.md`：团队编码规范与目录约定（可从 AGENTS.md 补充细化）
+- `需求文档/`：业务需求说明
+- `接口文档/`：后端接口约定
+- `部署文档.md`：构建、发布流程
+
+> 文档与代码同仓库维护，改代码的同时更新对应文档。

package/templates/vue3-vite/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/templates/vue3-vite/package.json.ejs

@@ -0,0 +1,36 @@
+{
+  "name": "<%= projectName %>",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --fix && prettier --write .<% if (useStylelint) { %> && stylelint \"**/*.{css,scss,vue}\" --fix<% } %>"
+  },
+  "dependencies": {
+    "@vueuse/core": "^11.0.0",
+    "axios": "^1.7.0",
+    "dayjs": "^1.11.0",
+    "echarts": "^5.5.0",
+    "element-plus": "^2.8.0",
+    "lodash-es": "^4.17.21",
+    "pinia": "^2.2.0",
+    "vue": "^3.5.0",
+    "vue-router": "^4.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-vue": "^9.0.0",
+    "prettier": "^3.3.0",
+    "sass": "^1.77.0",
+    "stylelint": "^16.0.0",
+    "stylelint-config-standard": "^36.0.0",
+    "unplugin-auto-import": "^0.18.0",
+    "unplugin-vue-components": "^0.27.0",
+    "vite": "^5.0.0"
+  }
+}

package/templates/vue3-vite/public/README.md

@@ -0,0 +1,7 @@
+# public — 静态资源目录
+
+此目录下的文件构建时会原样拷贝到 `dist/` 根路径，引用方式为绝对路径（如 `/favicon.ico`）。
+
+建议存放：favicon、不需要构建处理的静态文件、robots.txt 等。
+
+> 代码中通过 `@/src/assets/` 引入的图片走构建管线（可压缩、带 hash）；需要固定 URL 的文件才放这里。

package/templates/vue3-vite/src/App.vue

@@ -0,0 +1,3 @@
+<template>
+  <router-view />
+</template>

package/templates/vue3-vite/src/assets/README.md

@@ -0,0 +1,9 @@
+# assets — 项目资源目录
+
+存放需要走构建管线的静态资源：
+
+- `images/`：图片（会被压缩、加 hash，代码中用 `import img from '@/assets/images/xxx.png'` 引入）
+- `styles/`：全局样式（如 `variables.scss` 变量、`mixins.scss` 公共混入、`reset.scss`）
+- `fonts/`：字体文件
+
+> 与 `public/` 的区别：public 里的文件构建时原样拷贝、URL 固定；assets 里的文件经过 Vite 处理（压缩、hash、按需打包），优先用 assets。

package/templates/vue3-vite/src/components/README.md

@@ -0,0 +1,8 @@
+# components — 公共组件目录
+
+存放跨页面复用的公共组件，命名使用大驼峰（如 `DataTable.vue`、`SearchBar.vue`）。
+
+约定：
+1. 页面私有的组件放对应 `src/views/` 页面目录里，不要全部堆到这里
+2. 复杂组件建议配套 `components/xxx/` 目录形式（组件 + `index.vue` + 子组件）
+3. 组件 props 用 `defineProps` 显式声明类型，不透传未定义属性

package/templates/vue3-vite/src/main.js

@@ -0,0 +1,10 @@
+import { createApp } from 'vue';
+import { createPinia } from 'pinia';
+import App from './App.vue';
+import router from './router';
+
+// element-plus 组件由 unplugin-vue-components 按需自动注册，无需全量引入
+const app = createApp(App);
+app.use(createPinia());
+app.use(router);
+app.mount('#app');

package/templates/vue3-vite/src/router/index.js

@@ -0,0 +1,16 @@
+import { createRouter, createWebHistory } from 'vue-router';
+
+const routes = [
+  {
+    path: '/',
+    name: 'home',
+    component: () => import('../views/HomeView.vue'),
+  },
+];
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes,
+});
+
+export default router;

package/templates/vue3-vite/src/stores/counter.js

@@ -0,0 +1,12 @@
+import { defineStore } from 'pinia';
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+  }),
+  actions: {
+    increment() {
+      this.count++;
+    },
+  },
+});

package/templates/vue3-vite/src/utils/request.js

@@ -0,0 +1,25 @@
+import axios from 'axios';
+
+// 按项目实际后端地址修改，开发环境代理配置见 vite.config.js
+const request = axios.create({
+  baseURL: '/api',
+  timeout: 10000,
+});
+
+// 请求拦截器：统一带上 token
+request.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token');
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+// 响应拦截器：统一处理业务错误
+request.interceptors.response.use(
+  (response) => response.data,
+  (error) => {
+    console.error('请求异常：', error.message);
+    return Promise.reject(error);
+  }
+);
+
+export default request;

package/templates/vue3-vite/src/views/HomeView.vue

@@ -0,0 +1,31 @@
+<script setup>
+import { ref } from 'vue';
+import { useCounterStore } from '../stores/counter';
+
+const counter = useCounterStore();
+const now = ref('');
+
+const handleClick = () => {
+  counter.increment();
+  now.value = new Date().toLocaleTimeString();
+};
+
+// axios 请求已封装在 src/utils/request.js，用法：
+// import request from '@/utils/request';
+// request.get('/xxx').then((data) => {})
+</script>
+
+<template>
+  <div class="home">
+    <h1>Vue3 + Vite + Element Plus 项目已就绪</h1>
+    <el-button type="primary" @click="handleClick">点击了 {{ counter.count }} 次</el-button>
+    <p v-if="now">当前时间：{{ now }}（dayjs 可用于日期格式化）</p>
+  </div>
+</template>
+
+<style scoped lang="scss">
+.home {
+  padding: 40px;
+  text-align: center;
+}
+</style>

package/templates/vue3-vite/vite.config.js

@@ -0,0 +1,47 @@
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import AutoImport from 'unplugin-auto-import/vite';
+import Components from 'unplugin-vue-components/vite';
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers';
+import { fileURLToPath, URL } from 'node:url';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    // 自动导入 vue / vue-router / pinia 的 API（ref、computed、useRouter 等无需手动 import）
+    AutoImport({
+      imports: ['vue', 'vue-router', 'pinia'],
+      resolvers: [ElementPlusResolver()],
+    }),
+    // element-plus 组件按需自动注册
+    Components({
+      resolvers: [ElementPlusResolver()],
+    }),
+  ],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  server: {
+    host: '0.0.0.0',
+    proxy: {
+      // 按项目实际后端修改
+      '/api': {
+        target: 'http://localhost:8080',
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vue: ['vue', 'vue-router', 'pinia'],
+          'element-plus': ['element-plus'],
+          echarts: ['echarts'],
+        },
+      },
+    },
+  },
+});