vue 3项目应按业务模块组织src目录，如src/views/user/包含页面、api、类型和组合式函数；公共组件仅限跨模块复用且需明确定义用途、typescript声明props、规范插槽与事件；组合式函数替代工具函数，命名与路径需语义清晰。
Vue 3 项目初始化阶段，目录结构和公共组件标准不是“搭完架子就完事”的一步操作，而是团队协作的起点。规范做得早，后期改起来成本低；拖到多人并行、功能堆积后再重构，往往要重写接口调用、迁移状态逻辑、统一命名风格，反而更耗时。
按业务模块组织 src 目录，不按文件类型堆砌
避免把所有页面塞进 views/、所有组件扔进 components/、所有请求塞进 api/——这种纯技术分层会让开发者每次改一个功能都要跨 4–5 个目录找文件。
推荐结构（可直接落地）：
-
src/views/user/：包含
UserList.vue、UserProfile.vue、user.api.ts、user.types.ts、useUserSearch.ts - src/views/order/：同理，自有页面、API、类型、组合式函数全在本目录下
-
src/components/ 只放真正跨模块复用的组件，比如
BaseTable.vue、ConfirmDialog.vue，不放“用户头像”“订单状态标签”这类业务强耦合组件 - 业务组件优先放在对应 view 目录内，如
src/views/user/UserAvatar.vue，需要复用时再向上提取
公共组件开发必须带明确边界与契约
团队里最容易变成“黑盒垃圾场”的就是 components/。一个叫 Card.vue 的组件，可能在用户页渲染头像+昵称，在订单页显示金额+时间，在商品页又变成折叠面板——表面复用，实则隐式耦合。
规范做法：
vue-component-analyzer
下载
递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。
- 每个公共组件必须有清晰的用途定义，写在组件顶部注释里，例如：
// BaseCard：仅用于展示标题+描述+操作按钮，不支持嵌套表单或异步加载 - Props 必须用 TypeScript 显式声明，禁止
any或Object；可选 props 加?，必填项不加默认值 - 不接受“万能插槽”设计。如有
#header、#footer插槽，需在文档中说明适用场景和约束（比如 footer 插槽只允许放按钮，不支持文字或复杂布局） - 对外暴露的事件名用 kebab-case（如
@item-click），内部 emit 统一用 camelCase，通过 defineEmits 做类型校验
组合式函数（composables）代替工具函数，提升可测试性
别再往 utils/ 里塞一堆静态函数。像日期格式化、权限判断、表单校验这些逻辑，一旦和响应式、生命周期、Pinia store 打交道，纯工具函数就失效了。
正确姿势：
- 拆出 src/composables/ 目录，每个文件专注一个能力域，如
useAuth.ts、useTablePagination.ts、useFileUpload.ts - 函数名统一前缀
use，返回值必须是响应式对象或解构后的 ref/ref-like 值 - 内部可调用
onMounted、watch、useStore等，但不直接操作 DOM 或发起副作用请求；请求应封装在api/modules/下，由 composables 调用 - 对外提供明确的输入输出契约，比如
useTablePagination({ api: fetchList })，而不是让使用者传一堆参数去拼接 URL
命名与导入路径要“一眼懂用途”
命名不是审美问题，是协作效率问题。路径太长、名字太泛，新人花半小时都找不到“用户搜索框”在哪。
执行细则：
- 组件文件名用 PascalCase：
UserSearchForm.vue，不叫search.vue或user-search.vue - 组合式函数用
useXxx，TS 工具函数用xxxHelper.ts或xxxUtils.ts，区分语义 - 配置类文件统一后缀，如
router.config.ts、pinia.plugins.ts - Vite 配置路径别名
@/指向src/，@api指向src/api/modules，@comp指向src/components，减少相对路径出错
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
