Init-Vue3-Project

• Vue 官方教程
• Vue3 菜鸟教程

一、初始化项目

安装 NodeJS 并配置环境变量，可以使用 NVM 来管理 NodeJS 的版本

# 设置淘宝NPM仓库源
pnpm config set registry https://registry.npmmirror.com

# 获取仓库源信息
pnpm config get registry

通过 pnpm create vue@latest 一次性创建项目，无需交互式输入：

# 1. 创建项目
pnpm create vue@latest torch-web --ts --router --pinia --eslint --prettier

pnpm create vue@latest . --ts --router --pinia --eslint --prettier

# 2. 进入项目目录
cd torch-web

# 3. 安装依赖
pnpm install

# 4. 修改路由配置为 Hash 模式
# 编辑 src/router/index.ts

# 5. 修改 Vite 基础路径
# 编辑 vite.config.ts

# 6. 启动开发服务器
pnpm dev

参数说明：

• torch-web：您的项目名称（可自定义）
• . 表示当前目录作为项目路径
• --ts：使用 TypeScript
• --router：集成 Vue Router（需手动设为 Hash 模式以兼容 Electron）
• --pinia：集成 Pinia 状态管理
• --eslint：启用 ESLint 代码检查
• --prettier：集成 Prettier 代码格式化

关键兼容性配置：

创建后需在 src/router/index.ts 中将路由模式设为 Hash，并在 vite.config.ts 中设置基础路径：

// src/router/index.ts
import { createRouter, createWebHistory, createWebHashHistory } from 'vue-router'
export default createRouter({
  // 路由模式，默认为 history 可切换为hash
  // history: createWebHistory(import.meta.env.BASE_URL),
  history: createWebHashHistory(import.meta.env.BASE_URL),
  routes: [...]
})

// vite.config.ts
export default defineConfig({
  base: './', // 设为相对路径
  // ...其他配置
})

项目结构说明

.vscode                   // vscode配置文件夹
public                    // 静态资源文件夹，构建时文件会原封不动复制到dist根目录
  favicon.ico             // 网站页签图标文件
src                       // 项目源代码核心目录，所有业务代码、组件、逻辑均存放于此
  apis                    // 页面调用的后端API文件
  assets                  // 项目静态资源目录，Vite会对其中资源做编译（如图片hash命名）
  components              // 全局/通用组件目录，存放可复用的Vue组件
    ui                    // shadcn ui组件文件
  layouts                 // 页面布局文件
  router                  // 路由配置目录，存放Vue Router的路由规则、路由守卫等相关代码
  stores                  // Pinia状态管理目录，存放全局状态的store模块
  styles                  // 页面样式文件
  views                   // 页面级组件目录，存放对应路由的页面组件
  utils                   // 工具类，例如全局拦截器、请求工具、加密工具等
  App.vue                 // 根组件，项目所有页面的父容器，可配置全局布局、路由出口等
  main.ts                 // 项目入口文件，创建Vue实例、挂载根组件、配置全局插件等
  style.css               // 通用样式文件
.gitignore                // Git版本控制忽略文件配置
env.d.ts                  // TypeScript类型声明文件，解决TS类型提示问题
index.html                // 项目入口HTML文件，包含Vue挂载的根节点
package.json              // 项目依赖配置文件
README.md                 // 项目说明文档
tsconfig.app.json         // TypeScript针对Vue应用代码的编译配置，仅作用于src目录下的业务代码
tsconfig.json             // TypeScript根配置文件，全局通用的TS编译规则
tsconfig.node.json        // TypeScript针对Vite/node端代码的编译配置
vite.config.ts            // Vite构建工具的配置文件

# 安装pinia持久化插件
pnpm add pinia-plugin-persistedstate

import './assets/main.css'

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import piniaPersist from 'pinia-plugin-persistedstate';

import App from './App.vue'
import router from './router'

const app = createApp(App)
const pinia = createPinia();

pinia.use(piniaPersist); // 注册插件

app.use(pinia);
app.mount('#app');

app.mount('#app')

推送到Git仓库

git init
git config user.name "LiuHui"
git config user.email "whitetulips@163.com"

git add -A
git commit -m "Init project"

git remote add origin https://gitee.com/lorchr/torch-web.git
git remote add github https://github.com/lorchr/torch-web.git
git branch --set-upstream-to=origin/master master

git push -u origin master
git push -u github master

二、安装配置UI组件库

安装并配置 Tailwindcss

Shadcn UI for Vue 是基于 Tailwind CSS 构建的组件库，必须先配置 Tailwind CSS

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D postcss autoprefixer

创建 src/style.css

@import "tailwindcss";

修改 tsconfig.json

{
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.node.json"
    }
  ],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
}

修改 tsconfig.app.json

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
  "exclude": ["src/**/__tests__/*"],
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    
+    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

更新 vite 配置

pnpm add -D @types/node

修改 vite.config.ts

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
+ import tailwindcss from '@tailwindcss/vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    vue(),
+    tailwindcss(),
    vueDevTools(),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    },
  },
})

安装ShadCN-Vue

pnpm dlx shadcn-vue@latest init

# 选择默认的底色 Neutral

安装成功后会在项目根目录下创建 components.json

并在 src/style.css 中添加一些样式

可以使用以下命令添加组件

# 添加指定组件
pnpm dlx shadcn-vue@latest add button

# 添加所有组件
pnpm dlx shadcn-vue@latest add -a

# 命令选项
Usage: shadcn-vue add [options] [components...]

add a component to your project

Arguments:
  components         the components to add or a url to the component.

Options:
  -y, --yes           skip confirmation prompt. (default: false)
  -o, --overwrite     overwrite existing files. (default: false)
  -c, --cwd <cwd>     the working directory. defaults to the current directory. (default: "/Users/shadcn/Desktop")
  -a, --all           add all available components (default: false)
  -p, --path <path>   the path to add the component to.
  -s, --silent        mute output. (default: false)
  --src-dir           use the src directory when creating a new project. (default: false)
  --no-src-dir        do not use the src directory when creating a new project.
  --css-variables     use css variables for theming. (default: true)
  --no-css-variables  do not use css variables for theming.
  -h, --help          display help for command

组件将会被添加到 src/componments/ui 目录下，这个目录的位置在 components.json 指定的

在项目入口文件中添加css文件的引用

修改 index.html

<!DOCTYPE html>
<html lang="">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" href="/favicon.ico">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Vite App</title>
+    <link href="/src/style.css" rel="stylesheet">
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

添加一个测试页面

ShadCN.vue

<script setup lang="ts">
import { Button } from '@/components/ui/button'

</script>

<template>
  <div>
    <Button>Click me</Button>
  </div>
</template>

<style scoped>

</style>

三、绘制页面布局

# 安装图标
pnpm add lucide-vue-next