新手入门指南.md
9.67 KB
新手入门指南
最后更新: 2026-02-09 目的: 帮助新开发者快速上手项目
环境准备
1. 安装 Node.js
要求: Node.js 18.13.x
# 检查 Node.js 版本
node -v
# 如果版本不符合，安装 nvm
# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Windows
# 下载安装程序: https://github.com/coreybutler/nvm-windows/releases
# 安装 Node.js 18.13.x
nvm install 18.13.0
nvm use 18.13.0
2. 克隆项目
# 克隆项目
git clone <repository-url>
cd map-demo
# 安装依赖
npm install
3. 启动开发服务器
# 启动开发服务器（localhost）
npm run dev
# 启动开发服务器（网络访问）
npm run start
访问: http://localhost:8006
项目结构快速了解
核心目录
src/
├── api/ # API 接口
├── components/ # 公共组件
├── views/ # 页面组件
├── store/ # 状态管理
├── router/ # 路由配置
├── utils/ # 工具函数
└── common/ # 通用代码
关键文件
-
src/main.js- 入口文件 -
src/App.vue- 根组件 -
vite.config.js- Vite 配置 -
package.json- 项目依赖
开发工作流
1. 创建新页面
步骤 1: 创建页面文件
# 在 src/views/ 下创建页面目录
mkdir src/views/mypage
# 创建页面文件
touch src/views/mypage/index.vue
步骤 2: 编写页面组件
<!-- src/views/mypage/index.vue -->
<template>
<div class="mypage">
<h1>{{ title }}</h1>
<p>{{ content }}</p>
</div>
</template>
<script setup>
import { ref } from 'vue';
const title = ref('我的页面');
const content = ref('页面内容');
</script>
<style lang="less" scoped>
.mypage {
padding: 20px;
h1 {
font-size: 24px;
color: #333;
}
p {
font-size: 16px;
color: #666;
}
}
</style>
步骤 3: 添加路由
// src/router/routes/modules/mypage/index.js（创建新文件）
export default {
path: '/mypage',
name: 'MyPage',
component: () => import('@/views/mypage/index.vue'),
meta: {
title: '我的页面',
},
};
步骤 4: 访问页面
URL: http://localhost:8006/index.html#/index.html/mypage
2. 创建新组件
步骤 1: 创建组件文件
# 创建组件目录
mkdir src/components/MyComponent
# 创建组件文件
touch src/components/MyComponent/index.vue
步骤 2: 编写组件
<!-- src/components/MyComponent/index.vue -->
<template>
<div class="my-component">
<h2>{{ title }}</h2>
<slot></slot>
</div>
</template>
<script setup>
/**
* 我的组件
*
* @description 这是一个示例组件
* @component MyComponent
* @example
* <MyComponent title="标题">
* 内容
* </MyComponent>
*/
const props = defineProps({
/** 标题 */
title: {
type: String,
default: '',
},
});
const emit = defineEmits({
/** 点击事件 */
click: (payload) => true,
});
</script>
<style lang="less" scoped>
.my-component {
h2 {
font-size: 20px;
}
}
</style>
步骤 3: 使用组件
<template>
<div>
<MyComponent title="组件标题">
组件内容
</MyComponent>
</div>
</template>
<script setup>
import MyComponent from '@components/MyComponent/index.vue';
</script>
3. 添加 API 接口
步骤 1: 创建 API 文件
touch src/api/mypage.js
步骤 2: 定义 API
/**
* 我的页面 API
*
* @description 我的页面相关接口
*/
import { fn, fetch } from '@/api/fn';
const Api = {
MYPAGE: '/srv/?a=mypage',
};
/**
* 获取我的页面数据
*
* @param {Object} params - 请求参数
* @param {number} params.id - ID
* @returns {Promise<Object>} 响应数据
*/
export const myPageAPI = (params) => fn(fetch.get(Api.MYPAGE, params));
步骤 3: 使用 API
import { myPageAPI } from '@/api/mypage.js';
const { data } = await myPageAPI({ id: 123 });
if (data) {
console.log('获取数据成功:', data);
}
4. 添加状态管理
步骤 1: 创建 Store
// src/store/mypage.js
import { defineStore } from 'pinia';
export const useMyPageStore = defineStore('mypage', {
state: () => ({
data: null,
loading: false,
error: null,
}),
getters: {
hasData: (state) => state.data !== null,
},
actions: {
async fetchData(id) {
this.loading = true;
this.error = null;
try {
const { data } = await myPageAPI({ id });
this.data = data;
} catch (err) {
this.error = err.message;
} finally {
this.loading = false;
}
},
},
});
步骤 2: 使用 Store
<script setup>
import { useMyPageStore } from '@/store/mypage';
import { onMounted } from 'vue';
const myPageStore = useMyPageStore();
onMounted(() => {
myPageStore.fetchData(123);
});
</script>
<template>
<div v-if="myPageStore.loading">加载中...</div>
<div v-else-if="myPageStore.error">{{ myPageStore.error }}</div>
<div v-else>{{ myPageStore.data }}</div>
</template>
常见开发任务
修改样式
<template>
<div class="page">内容</div>
</template>
<style lang="less" scoped>
.page {
/* 使用 Less */
padding: 20px;
/* 嵌套选择器 */
h1 {
font-size: 24px;
/* 伪元素 */
&:hover {
color: blue;
}
}
}
</style>
添加路由跳转
import { useRouter } from 'vue-router';
const router = useRouter();
// 方式 1: 路径跳转
router.push('/mypage');
// 方式 2: 命名路由
router.push({ name: 'MyPage' });
// 方式 3: 带参数跳转
router.push({
name: 'MyPage',
query: { id: 123 }
});
// 方式 4: 带参数跳转（Hash 模式）
router.push('/index.html/mypage?id=123');
使用 Vant 组件
<template>
<!-- Vant 组件自动导入，无需手动 import -->
<van-button type="primary">按钮</van-button>
<van-cell-group>
<van-cell title="单元格" value="内容" />
</van-cell-group>
<van-image :src="image_url" />
</template>
使用 Element Plus 组件
<template>
<!-- Element Plus 组件自动导入，无需手动 import -->
<el-button type="primary">按钮</el-button>
<el-table :data="tableData">
<el-table-column prop="name" label="姓名" />
</el-table>
</template>
处理响应式数据
import { ref, reactive, computed } from 'vue';
// ref：基本类型
const count = ref(0);
const message = ref('Hello');
// reactive：对象类型
const user = reactive({
name: '',
age: 0,
});
// computed：计算属性
const fullName = computed(() => {
return `${user.name} (${user.age}岁)`;
});
// 修改数据
count.value++; // ref 需要 .value
user.name = '张三'; // reactive 不需要 .value
调试技巧
1. 使用 VConsole
// 引入 VConsole
import { initVConsole } from '@/utils/vconsole';
// 在开发环境启用
if (import.meta.env.DEV) {
initVConsole();
}
2. 查看状态
// 在控制台查看 Pinia 状态
import { useMainStore } from '@/store';
const mainStore = useMainStore();
console.log('Main Store:', mainStore.$state);
3. 查看路由
// 查看当前路由
import { useRoute } from 'vue-router';
const route = useRoute();
console.log('当前路由:', route.path, route.query, route.params);
部署
本地构建
# 构建
npm run build
# 预览
npm run serve
部署到服务器
# 开发环境
npm run dev_upload
# OA 环境
npm run oa_upload
# Walk 环境
npm run walk_upload
# XYS 环境
npm run xys_upload
常见问题
Q1: 组件自动导入不生效？
A: 检查 vite.config.js 中的组件解析器配置。
Components({
resolvers: [VantResolver(), ElementPlusResolver()],
}),
Q2: API 自动导入不生效？
A: 检查 vite.config.js 中的自动导入配置。
AutoImport({
imports: ['vue', 'vue-router'],
dts: 'src/auto-imports.d.ts',
}),
Q3: 路由跳转 404？
A: 检查路由是否包含 #/index.html 前缀。
// ✅ 正确
router.push('/index.html/mypage')
// ❌ 错误
router.push('/mypage')
Q4: 样式不生效？
A: 检查是否添加了 scoped。
<style lang="less" scoped>
/* 添加 scoped */
</style>
Q5: 图片加载失败？
A: 检查图片路径是否正确。
// ✅ 正确：使用别名
const imageUrl = ref('@images/logo.png');
// ✅ 正确：使用绝对路径
const imageUrl = ref('/images/logo.png');
// ❌ 错误：相对路径
const imageUrl = ref('../../images/logo.png');
学习资源
Vue 3
Vant
Element Plus
Pinia
Vue Router
下一步
祝开发顺利！🎉