1. 为什么 Vue 项目一到 CI/CD 就“卡壳”如果你正在维护一个中大型 Vue 项目大概率遇到过这种场景本地npm run serve跑得好好的一推到流水线就各种玄学问题——构建产物路径对不上、环境变量串了、多入口项目只能手动改配置、每次全量构建十几分钟起步。前端团队想引入 AI 编程工具提效结果工具生成的代码在 CI 里跑不通反而增加了排查成本。Stagewise 这个工具本质上就是来解决“多阶段构建 环境隔离 流水线可复现”这三件事的。它不是一个全新的构建器而是架在 Webpack 之上的一层阶段编排层让你用一份配置描述清楚 admin、mobile、customer 这些不同入口在不同环境下的构建行为然后交给 CI 去执行。适合谁用适合那些 Vue 项目已经超过单入口、环境超过两套、团队超过三个人的前端团队。我试过在一个 6 入口的 Vue2 老项目里接入 Stagewise配合流水线做分阶段构建构建耗时从原来的全量 14 分钟压到了按需 5 分钟出头。下面把可复制的配置骨架和验证动作完整拆一遍你照着改就能落地。2. 接入前的准备TaoToken 与 AI 编程工具链Stagewise 本身负责构建编排但如果你想让 AI 编程工具比如 Claude Code、Cursor 这类在生成 Vue 组件时能直接理解你的 Stage 结构就需要一个稳定的模型调用入口。这里我用的是 TaoToken 的 API 服务它提供兼容 OpenAI 格式的接口可以直接在 CI 脚本或本地调试脚本里调用。先拿到 API Key访问 https://taotoken.net/api-keys 创建一个密钥注意这个 Key 只在创建时显示一次复制后存到 CI 的 Secret 变量里不要写进仓库。如果你只是想在本地验证模型输出是否符合 Stage 配置规范可以用模型对话页面快速试https://taotoken.net/model-chat 。长期做编码和 Agent 任务的团队建议直接上 Coding Plan省得每次手动配环境https://taotoken.net/coding-plan 。接入文档在这里遇到参数问题先查这个https://taotoken.net/doc 。API 基础地址是https://taotoken.net/api注意不要加多余的路径后缀兼容模式下直接拼/v1/chat/completions即可。3. 可复制的 Stagewise 配置骨架3.1 安装与目录约定在 Vue 项目根目录执行npm install stagewise --save-dev touch stagewise.config.js推荐的目录结构是这样的重点是每个 Stage 有独立入口和环境文件project-root/ ├── stagewise.config.js ├── package.json ├── .env.stage.admin ├── .env.stage.mobile ├── vue.config.js └── src/ ├── main.js ├── admin.js ├── mobile.js └── components/3.2 核心配置文件stagewise.config.js是整个接入的心脏它描述每个 Stage 的入口、环境文件和输出目录// stagewise.config.js module.exports { stages: { admin: { entry: src/admin.js, env: .env.stage.admin, output: dist/admin, publicPath: /admin/ }, mobile: { entry: src/mobile.js, env: .env.stage.mobile, output: dist/mobile, publicPath: /mobile/ } }, shared: { modules: [src/components, src/utils], splitChunks: { minSize: 30000, cacheGroups: { vendor: { test: /[\\/]node_modules[\\/]/, name: vendors, chunks: all } } } }, devServer: { port: 8081, proxy: { /api: { target: process.env.VUE_APP_API_URL, changeOrigin: true } } } };这里有几个关键点shared.modules声明了跨 Stage 共享的目录Stagewise 会基于这个配置做 SplitChunks 提取避免每个 Stage 重复打包公共组件。publicPath单独配置是因为多 Stage 部署时通常挂在不同的子路径下CI 里如果路径写死会导致静态资源 404。3.3 接入 Vue CLI 的 Webpack 链路Vue CLI 项目通过vue.config.js挂载 Stagewise 插件// vue.config.js const StageWise require(stagewise); module.exports { publicPath: process.env.VUE_APP_PUBLIC_PATH || /, configureWebpack: (config) { config.plugins.push( new StageWise.StagePlugin({ currentStage: process.env.VUE_APP_STAGE, sharedModules: [src/components, src/utils] }) ); }, chainWebpack: (config) { if (process.env.VUE_APP_STAGE) { config.entry(app).clear().add(./src/${process.env.VUE_APP_STAGE}.js); } } };chainWebpack里动态切换 entry 是关键一步这样--stageadmin时实际入口就是src/admin.js不需要维护多份 webpack 配置。3.4 构建脚本与流水线触发package.json里加上分阶段脚本{ scripts: { serve:admin: cross-env VUE_APP_STAGEadmin stagewise serve --stageadmin, build:admin: cross-env VUE_APP_STAGEadmin stagewise build --stageadmin, build:mobile: cross-env VUE_APP_STAGEmobile stagewise build --stagemobile, build:all: stagewise build --all, analyze:admin: stagewise analyze --stageadmin } }GitLab CI 的触发配置按 Stage 拆成独立 job互不阻塞# .gitlab-ci.yml stages: - build - test - deploy variables: TAOTOKEN_API_BASE: https://taotoken.net/api build_admin: stage: build script: - npm ci - npm run build:admin artifacts: paths: - dist/admin/ expire_in: 1 day only: changes: - src/admin.js - src/components/**/* - stagewise.config.js build_mobile: stage: build script: - npm ci - npm run build:mobile artifacts: paths: - dist/mobile/ expire_in: 1 day only: changes: - src/mobile.js - src/components/**/* - stagewise.config.jsonly.changes这块是效能提升的核心——只有对应 Stage 的入口或共享模块变了才触发构建避免改一个 admin 页面把 mobile 也重新打一遍。4. 验证请求与成功结果配置写完后先本地验证 Stage 切换是否生效npm run build:admin ls dist/admin/ # 应该看到 index.html、js/、css/ 等产物然后验证环境变量是否正确注入。在src/admin.js里加一行临时日志console.log(API URL:, process.env.VUE_APP_API_URL); console.log(Stage:, process.env.VUE_APP_STAGE);构建后搜索产物文件grep -r api-admin dist/admin/js/ | head -3如果能看到注入后的地址说明 DefinePlugin 链路通了。接着验证 AI 编程工具的调用是否正常用 curl 测一下 TaoToken 的接口curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 生成一个 Vue3 的表格组件骨架}] }返回 200 且 body 里有choices字段说明 Key 和网络都正常。CI 里把这个 curl 作为 smoke test 放在 build 之前能提前拦住 Key 过期或配额问题。流水线跑通后你会在 GitLab 的 pipeline 页面看到 admin 和 mobile 两个 job 并行执行各自产出独立的 artifacts。部署阶段按 Stage 分别拉取对应产物即可。5. 本篇常见错排查报错一Cannot find module src/admin.js原因通常是chainWebpack里的 entry 路径没加./前缀或者VUE_APP_STAGE环境变量在 CI 里没传进去。检查cross-env是否装在了 devDependencies 里CI 的npm ci默认不装 devDependencies 的话要加--includedev。报错二构建产物里环境变量是 undefinedStagewise 默认只注入VUE_APP_前缀的变量检查.env.stage.admin里的变量名是否带了这个前缀。另外.env.stage.admin文件本身不要提交到仓库用 CI 的 variables 注入或者用.env.stage.admin.example做模板。报错三CI 里构建成功但部署后静态资源 404九成是publicPath没配对。多 Stage 部署到子路径时publicPath必须和实际访问路径一致。可以在 CI 里用VUE_APP_PUBLIC_PATH动态覆盖部署脚本里根据 Stage 名拼出路径。报错四AI 工具生成的代码在 CI 里 lint 不过Stagewise 本身不管 lint但 AI 生成的代码风格可能和项目 ESLint 规则冲突。建议在 CI 的 build job 之前加一个 lint job用--max-warnings0卡住。如果频繁冲突可以在 TaoToken 的模型对话里先让模型按你的 ESLint 配置生成代码再贴进项目。报错五stagewise build --all时内存溢出多 Stage 并行构建时 Node 默认堆内存不够。在 CI 脚本里加NODE_OPTIONS--max-old-space-size4096或者把--all拆成多个 job 并行跑反而更快。6. 从集成到跃迁下一步怎么走Stagewise 接入完成后真正的效能提升来自两件事一是把 Stage 划分和 CI 触发规则对齐让每次提交只构建受影响的 Stage二是把 AI 编程工具的输出纳入 Stage 验证流程生成即验证避免人工返工。如果你还在手动管理 API Key 和模型调用建议把 TaoToken 的接入文档过一遍里面有 CI 环境下的密钥轮换和配额管理方案https://taotoken.net/doc 。需要长期跑编码 Agent 的团队Coding Plan 比按次调用更划算配置入口在 https://taotoken.net/coding-plan 。本地调试阶段想快速验证模型输出直接用模型对话页面就行不用写代码https://taotoken.net/model-chat 。最后提醒一句Stagewise 的配置文件一定要纳入版本管理但.env.stage.*不要提交。CI 里用 Secret 注入环境变量本地用.env.stage.*.local覆盖这样既保证流水线可复现又不会泄露敏感配置。
Stagewise 使用指南：Vue 项目集成到 CI/CD 效能跃迁的深度解析
1. 为什么 Vue 项目一到 CI/CD 就“卡壳”如果你正在维护一个中大型 Vue 项目大概率遇到过这种场景本地npm run serve跑得好好的一推到流水线就各种玄学问题——构建产物路径对不上、环境变量串了、多入口项目只能手动改配置、每次全量构建十几分钟起步。前端团队想引入 AI 编程工具提效结果工具生成的代码在 CI 里跑不通反而增加了排查成本。Stagewise 这个工具本质上就是来解决“多阶段构建 环境隔离 流水线可复现”这三件事的。它不是一个全新的构建器而是架在 Webpack 之上的一层阶段编排层让你用一份配置描述清楚 admin、mobile、customer 这些不同入口在不同环境下的构建行为然后交给 CI 去执行。适合谁用适合那些 Vue 项目已经超过单入口、环境超过两套、团队超过三个人的前端团队。我试过在一个 6 入口的 Vue2 老项目里接入 Stagewise配合流水线做分阶段构建构建耗时从原来的全量 14 分钟压到了按需 5 分钟出头。下面把可复制的配置骨架和验证动作完整拆一遍你照着改就能落地。2. 接入前的准备TaoToken 与 AI 编程工具链Stagewise 本身负责构建编排但如果你想让 AI 编程工具比如 Claude Code、Cursor 这类在生成 Vue 组件时能直接理解你的 Stage 结构就需要一个稳定的模型调用入口。这里我用的是 TaoToken 的 API 服务它提供兼容 OpenAI 格式的接口可以直接在 CI 脚本或本地调试脚本里调用。先拿到 API Key访问 https://taotoken.net/api-keys 创建一个密钥注意这个 Key 只在创建时显示一次复制后存到 CI 的 Secret 变量里不要写进仓库。如果你只是想在本地验证模型输出是否符合 Stage 配置规范可以用模型对话页面快速试https://taotoken.net/model-chat 。长期做编码和 Agent 任务的团队建议直接上 Coding Plan省得每次手动配环境https://taotoken.net/coding-plan 。接入文档在这里遇到参数问题先查这个https://taotoken.net/doc 。API 基础地址是https://taotoken.net/api注意不要加多余的路径后缀兼容模式下直接拼/v1/chat/completions即可。3. 可复制的 Stagewise 配置骨架3.1 安装与目录约定在 Vue 项目根目录执行npm install stagewise --save-dev touch stagewise.config.js推荐的目录结构是这样的重点是每个 Stage 有独立入口和环境文件project-root/ ├── stagewise.config.js ├── package.json ├── .env.stage.admin ├── .env.stage.mobile ├── vue.config.js └── src/ ├── main.js ├── admin.js ├── mobile.js └── components/3.2 核心配置文件stagewise.config.js是整个接入的心脏它描述每个 Stage 的入口、环境文件和输出目录// stagewise.config.js module.exports { stages: { admin: { entry: src/admin.js, env: .env.stage.admin, output: dist/admin, publicPath: /admin/ }, mobile: { entry: src/mobile.js, env: .env.stage.mobile, output: dist/mobile, publicPath: /mobile/ } }, shared: { modules: [src/components, src/utils], splitChunks: { minSize: 30000, cacheGroups: { vendor: { test: /[\\/]node_modules[\\/]/, name: vendors, chunks: all } } } }, devServer: { port: 8081, proxy: { /api: { target: process.env.VUE_APP_API_URL, changeOrigin: true } } } };这里有几个关键点shared.modules声明了跨 Stage 共享的目录Stagewise 会基于这个配置做 SplitChunks 提取避免每个 Stage 重复打包公共组件。publicPath单独配置是因为多 Stage 部署时通常挂在不同的子路径下CI 里如果路径写死会导致静态资源 404。3.3 接入 Vue CLI 的 Webpack 链路Vue CLI 项目通过vue.config.js挂载 Stagewise 插件// vue.config.js const StageWise require(stagewise); module.exports { publicPath: process.env.VUE_APP_PUBLIC_PATH || /, configureWebpack: (config) { config.plugins.push( new StageWise.StagePlugin({ currentStage: process.env.VUE_APP_STAGE, sharedModules: [src/components, src/utils] }) ); }, chainWebpack: (config) { if (process.env.VUE_APP_STAGE) { config.entry(app).clear().add(./src/${process.env.VUE_APP_STAGE}.js); } } };chainWebpack里动态切换 entry 是关键一步这样--stageadmin时实际入口就是src/admin.js不需要维护多份 webpack 配置。3.4 构建脚本与流水线触发package.json里加上分阶段脚本{ scripts: { serve:admin: cross-env VUE_APP_STAGEadmin stagewise serve --stageadmin, build:admin: cross-env VUE_APP_STAGEadmin stagewise build --stageadmin, build:mobile: cross-env VUE_APP_STAGEmobile stagewise build --stagemobile, build:all: stagewise build --all, analyze:admin: stagewise analyze --stageadmin } }GitLab CI 的触发配置按 Stage 拆成独立 job互不阻塞# .gitlab-ci.yml stages: - build - test - deploy variables: TAOTOKEN_API_BASE: https://taotoken.net/api build_admin: stage: build script: - npm ci - npm run build:admin artifacts: paths: - dist/admin/ expire_in: 1 day only: changes: - src/admin.js - src/components/**/* - stagewise.config.js build_mobile: stage: build script: - npm ci - npm run build:mobile artifacts: paths: - dist/mobile/ expire_in: 1 day only: changes: - src/mobile.js - src/components/**/* - stagewise.config.jsonly.changes这块是效能提升的核心——只有对应 Stage 的入口或共享模块变了才触发构建避免改一个 admin 页面把 mobile 也重新打一遍。4. 验证请求与成功结果配置写完后先本地验证 Stage 切换是否生效npm run build:admin ls dist/admin/ # 应该看到 index.html、js/、css/ 等产物然后验证环境变量是否正确注入。在src/admin.js里加一行临时日志console.log(API URL:, process.env.VUE_APP_API_URL); console.log(Stage:, process.env.VUE_APP_STAGE);构建后搜索产物文件grep -r api-admin dist/admin/js/ | head -3如果能看到注入后的地址说明 DefinePlugin 链路通了。接着验证 AI 编程工具的调用是否正常用 curl 测一下 TaoToken 的接口curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 生成一个 Vue3 的表格组件骨架}] }返回 200 且 body 里有choices字段说明 Key 和网络都正常。CI 里把这个 curl 作为 smoke test 放在 build 之前能提前拦住 Key 过期或配额问题。流水线跑通后你会在 GitLab 的 pipeline 页面看到 admin 和 mobile 两个 job 并行执行各自产出独立的 artifacts。部署阶段按 Stage 分别拉取对应产物即可。5. 本篇常见错排查报错一Cannot find module src/admin.js原因通常是chainWebpack里的 entry 路径没加./前缀或者VUE_APP_STAGE环境变量在 CI 里没传进去。检查cross-env是否装在了 devDependencies 里CI 的npm ci默认不装 devDependencies 的话要加--includedev。报错二构建产物里环境变量是 undefinedStagewise 默认只注入VUE_APP_前缀的变量检查.env.stage.admin里的变量名是否带了这个前缀。另外.env.stage.admin文件本身不要提交到仓库用 CI 的 variables 注入或者用.env.stage.admin.example做模板。报错三CI 里构建成功但部署后静态资源 404九成是publicPath没配对。多 Stage 部署到子路径时publicPath必须和实际访问路径一致。可以在 CI 里用VUE_APP_PUBLIC_PATH动态覆盖部署脚本里根据 Stage 名拼出路径。报错四AI 工具生成的代码在 CI 里 lint 不过Stagewise 本身不管 lint但 AI 生成的代码风格可能和项目 ESLint 规则冲突。建议在 CI 的 build job 之前加一个 lint job用--max-warnings0卡住。如果频繁冲突可以在 TaoToken 的模型对话里先让模型按你的 ESLint 配置生成代码再贴进项目。报错五stagewise build --all时内存溢出多 Stage 并行构建时 Node 默认堆内存不够。在 CI 脚本里加NODE_OPTIONS--max-old-space-size4096或者把--all拆成多个 job 并行跑反而更快。6. 从集成到跃迁下一步怎么走Stagewise 接入完成后真正的效能提升来自两件事一是把 Stage 划分和 CI 触发规则对齐让每次提交只构建受影响的 Stage二是把 AI 编程工具的输出纳入 Stage 验证流程生成即验证避免人工返工。如果你还在手动管理 API Key 和模型调用建议把 TaoToken 的接入文档过一遍里面有 CI 环境下的密钥轮换和配额管理方案https://taotoken.net/doc 。需要长期跑编码 Agent 的团队Coding Plan 比按次调用更划算配置入口在 https://taotoken.net/coding-plan 。本地调试阶段想快速验证模型输出直接用模型对话页面就行不用写代码https://taotoken.net/model-chat 。最后提醒一句Stagewise 的配置文件一定要纳入版本管理但.env.stage.*不要提交。CI 里用 Secret 注入环境变量本地用.env.stage.*.local覆盖这样既保证流水线可复现又不会泄露敏感配置。
