Nuxt3 + Vue3 Composition API + TS + Vite + Ant Design Vue 企业级项目实战：从零到部署

1. 环境准备与项目初始化最近接手了一个企业级中后台项目技术栈选型上毫不犹豫选择了Nuxt3Vue3的组合。这套组合拳在开发效率和性能表现上确实让人惊喜不过从零开始搭建时还是踩了不少坑这里把完整流程梳理出来分享给大家。首先确保你的开发环境满足以下要求Node.js版本≥16.10推荐18.x LTS版本npm≥8.x或yarn≥1.22推荐使用VSCodeVolta工具链管理Node版本创建项目时我强烈推荐使用nuxi这个官方CLI工具它能自动生成最优的项目结构。执行下面这行命令就能快速初始化npx nuxi init my-project初始化完成后你会看到这样的目录结构├── assets/ # 静态资源 ├── components/ # 公共组件 ├── composables/ # 组合式函数 ├── layouts/ # 布局文件 ├── pages/ # 页面路由 ├── plugins/ # 插件注册 ├── public/ # 纯静态文件 ├── server/ # 服务端API ├── stores/ # Pinia状态管理 ├── nuxt.config.ts # 核心配置文件 └── tsconfig.json # TS类型配置这里有个小技巧在nuxt.config.ts中建议立即配置以下基础选项export default defineNuxtConfig({ typescript: { strict: true, // 开启严格类型检查 typeCheck: true // 开发时进行类型检查 }, vite: { css: { preprocessorOptions: { less: { javascriptEnabled: true // Ant Design Vue需要 } } } } })2. 核心依赖集成实战2.1 Ant Design Vue深度整合企业级项目少不了UI组件库Ant Design Vue的Pro版组件特别适合中后台场景。安装时要注意版本兼容性npm install ant-design-vue4.x ant-design/icons-vue在plugins/antd.ts中配置全局加载时我推荐采用按需引入方式减小打包体积import { Button, Form, Table } from ant-design-vue export default defineNuxtPlugin(nuxtApp { nuxtApp.vueApp .use(Button) .use(Form) .use(Table) })主题定制可以通过两种方式实现运行时动态主题适合需要换肤功能的场景构建时静态主题性能更优这里分享一个构建时主题配置方案在nuxt.config.ts中添加vite: { css: { preprocessorOptions: { less: { modifyVars: { primary-color: #1890ff, border-radius-base: 4px }, javascriptEnabled: true } } } }2.2 状态管理进阶方案Pinia作为Vuex的替代者在Nuxt3中的集成异常简单。首先安装必要依赖npm install pinia pinia/nuxt pinia-plugin-persistedstate在stores目录下创建用户状态模块时我通常会这样组织代码// stores/user.ts export const useUserStore defineStore(user, () { const token ref() const userInfo refPartialUser({}) const isAdmin computed(() userInfo.value.role admin) function login(credentials: LoginDto) { return api.login(credentials).then(res { token.value res.token userInfo.value res.user }) } return { token, userInfo, isAdmin, login } }, { persist: { storage: persistedState.cookiesWithOptions({ sameSite: strict }) } })在组件中使用时这种组合式写法比Options API更加灵活const { user, isAdmin } storeToRefs(useUserStore()) const { login } useUserStore()3. 工程化配置技巧3.1 Vite深度优化Nuxt3默认使用Vite作为构建工具我们可以通过配置大幅提升开发体验// nuxt.config.ts export default defineNuxtConfig({ vite: { build: { chunkSizeWarningLimit: 1500, rollupOptions: { output: { manualChunks: { ant-design-vue: [ant-design-vue], lodash: [lodash-es] } } } }, server: { proxy: { /api: { target: http://backend:3000, changeOrigin: true } } } } })3.2 自动化导入配置Nuxt3的auto-imports功能可以大幅减少样板代码但需要合理配置// nuxt.config.ts export default defineNuxtConfig({ imports: { dirs: [ composables/**, stores/**, utils/** ] }, components: { dirs: [ components/common, components/layout, { path: components/business, prefix: Biz } ] } })这样在代码中就可以直接使用这些目录下的功能无需手动导入。比如在任意组件中const { formatDate } useUtils() // 自动从utils目录导入4. 生产环境部署4.1 构建优化配置在部署前建议调整构建配置// nuxt.config.ts export default defineNuxtConfig({ nitro: { preset: node-server, compressPublicAssets: true }, experimental: { payloadExtraction: true, inlineSSRStyles: false }, app: { buildAssetsDir: /_nuxt/, cdnURL: process.env.CDN_URL || } })4.2 PM2高级配置对于生产环境我推荐使用PM2的cluster模式// ecosystem.config.js module.exports { apps: [{ name: my-app, script: ./.output/server/index.mjs, instances: max, exec_mode: cluster, env: { NITRO_PORT: 3000, NODE_ENV: production }, max_memory_restart: 1G, error_file: ./logs/err.log, out_file: ./logs/out.log, merge_logs: true }] }启动时建议配合Nginx做负载均衡upstream nuxt_app { server 127.0.0.1:3000; } server { listen 80; server_name yourdomain.com; location / { proxy_pass http://nuxt_app; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; } }部署过程中常见的一个坑是静态资源404问题解决方案是在Nginx配置中添加location /_nuxt/ { alias /path/to/project/.output/public/_nuxt/; expires 1y; add_header Cache-Control public; }