Vue3项目架构全面解析：从核心目录到配置实战

Vue3项目架构全面解析：从核心目录到配置实战

【免费下载链接】oh-my-cvAn in-browser, local-first Markdown resume builder.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-cv

项目架构全景图：核心目录功能矩阵

💡架构设计技巧：项目采用"核心功能模块化+应用层集成"的双层架构，packages/目录下的独立模块（如gfonts-loader、dynamic-css）可单独发布为npm包，实现跨项目复用。

核心文件功能解析：从入口到渲染

应用入口文件：site/src/app.vue

作为Nuxt.js应用的根组件，承担页面骨架构建职责：

<template> <div id="app"> <Header /> <NuxtPage /> </div> </template>

⚠️注意事项：该文件不直接包含业务逻辑，主要负责全局布局和公共组件引入，修改时需注意影响所有页面。

状态管理核心：site/src/composables/stores/style.ts

使用Vue3的Pinia（状态管理库）管理样式配置：

export const useStyleStore = defineStore('style', { state: () => ({ fontSize: 14, fontFamily: 'serif', // 更多样式状态... }), actions: { updateFontSize(size) { this.fontSize = size; } } })

💡性能优化：通过storeToRefs解构状态可保持响应式，避免不必要的组件重渲染。

路由配置机制：基于文件系统的路由

Nuxt.js会自动根据site/src/pages/目录结构生成路由，例如：

• pages/index.vue→/
• pages/[...lang]/resumes.vue→/:lang/resumes

⚠️路由陷阱：动态路由（如[id].vue）需通过useRoute()获取参数，开发时需注意类型定义。

配置指南：从开发到部署

项目依赖管理：package.json核心配置

{ "scripts": { "dev": "nuxt dev", "build": "nuxt build", "generate": "nuxt generate" }, "dependencies": { "vue": "^3.3.4", "@nuxtjs/i18n": "^8.0.0" } }

💡依赖管理技巧：使用pnpm作为包管理器时，通过pnpm-workspace.yaml可实现多包项目的依赖共享。

TypeScript配置：tsconfig.base.json

{ "compilerOptions": { "target": "ESNext", "module": "ESNext", "moduleResolution": "Node", "strict": true, "jsx": "preserve", "sourceMap": true } }

⚠️类型安全提示：保持strict: true可在开发阶段捕获类型错误，但需为第三方库添加类型声明（.d.ts）。

国际化配置：site/configs/i18n.ts

export default { locales: [ { code: 'en', name: 'English' }, { code: 'zh-cn', name: '中文' } ], defaultLocale: 'zh-cn' }

新手常见问题与解决方案

Q1：如何添加自定义字体？

A：需完成三步：

1. 将字体文件放入site/src/assets/fonts/目录
2. 在site/src/utils/font.ts中注册字体信息
3. 在FontFamily.vue组件中添加选项

Q2：修改样式后页面无变化？

A：可能原因：

• 样式被CSS模块化隔离，需使用:global()包裹全局样式
• 缓存问题，可执行pnpm dev --force重启开发服务器
• 样式优先级问题，使用浏览器开发工具检查具体生效规则

Q3：如何调试Markdown解析问题？

A：推荐调试路径：

1. 检查packages/markdown-it-*系列插件的解析逻辑
2. 使用site/src/utils/markdown.ts中的parseMarkdown函数进行单元测试
3. 查看浏览器控制台的markdown-render相关日志

开发环境搭建指南

1. 克隆项目代码库：

git clone https://gitcode.com/gh_mirrors/oh/oh-my-cv

2. 安装依赖：

cd oh-my-cv pnpm install

3. 启动开发服务器：

pnpm dev

💡开发效率提示：使用pnpm run dev --open可自动打开浏览器，并支持热模块替换（HMR），代码修改后无需手动刷新页面。

【免费下载链接】oh-my-cvAn in-browser, local-first Markdown resume builder.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-cv