# @creativestyle/magesuite-frontend-builder 中文文档 规范地址：https://npmcn.com/package/%40creativestyle/magesuite-frontend-builder/ 版本：5\.1\.0 npm 元数据更新时间：2026-10-21T10:23:14.530Z 中文译文更新时间：2026-11-11T01:22:41.238Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40creativestyle/magesuite-frontend-builder 原文对照：https://npmcn.com/package/%40creativestyle/magesuite-frontend-builder/?lang=original 项目主页：https://github.com/magesuite/frontend-builder#readme 源码仓库：https://github.com/magesuite/frontend-builder ## 关键信息（来自 npm 元数据） - 包体积（解压后）：156 kB，51 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=22\.22\.1 - 运行依赖：51 个 - 首次发布：2018-11-13T13:13:56.966Z - 最新版本发布：2026-10-21T10:23:14.190Z - 近 30 天下载量：2280（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：71（近 12 个月 4 个） ## 中文简介 Magento 2 / MageSuite主题的现代构建系统 **网页包 5**, (中文(简体) ), **类型脚本**,以及 **纸浆5**. 提供 Webpack 捆绑,SCSS 编译,资产复制,图像优化,linting,浏览器Sync Dev 代理,以及 Magento 缓存管理- a ## 安装 ```sh npm install @creativestyle/magesuite-frontend-builder ``` 也可以使用：`pnpm add @creativestyle/magesuite-frontend-builder`、`yarn add @creativestyle/magesuite-frontend-builder`、`bun add @creativestyle/magesuite-frontend-builder` ## README # @creativetyle/magesite-frontend-buildinger (英语) Magento 2 / MageSuite主题的现代构建系统 **网页包 5**, (中文(简体) ), **类型脚本**,以及 **纸浆5**. 提供webpack捆绑,SCSS编译,资产复制,图像优化,linting,浏览器Sync dev代理,和Magento缓存管理——都用被儿童主题所消耗的单个包连接在一起. * * * ## 特征 - **网页包 5** 包含 TypeScript 编译和持久文件系统缓存 - **热CSS注射** 通过浏览器Sync – 没有页面重载样式变化 - **多层次主题继承** ——文件解析度走满 `theme.xml` 父链 - **现代工具** ——ESLint平面配置 Stylelint v17, Prettier, Husky v9, lint-staged (英语) - **交互式命令菜单** —— 说 `yarn menu` 所有可用任务的箭头键导航 - **生产优化** —— CSS minification, 图像压缩, WOFF2- 只用字体 * * * ## 快开始 ```bash yarn install yarn menu # interactive command menu — recommended starting point yarn build # production build yarn build:verbose # production build with full asset size report yarn serve # development watch mode with BrowserSync yarn lint # ESLint + Stylelint yarn lint:js # ESLint only yarn lint:css # Stylelint only ``` 个人gulp任务也可以直接运行. 使用 `yarn gulp ` - 不裸着 `gulp ` (没有全局安装)而不是 `yarn ` (这些任务未列在 `package.json` 脚本 : ```bash yarn gulp cleanWebpackCache # wipe webpack filesystem cache yarn gulp eslint --fix # lint and auto-fix JS/TS yarn gulp stylelint --fix # lint and auto-fix SCSS ``` * * * ## 目录结构 ``` magesuite-frontend-builder/ ├── registry.js # Entry point — registers all tasks and composes build/serve/watch ├── menu.js # Interactive CLI menu binary (magesuite-menu) ├── eslint.config.js # ESLint flat config (JS + TS, Prettier integration) ├── package.json │ ├── config/ # Theme-level config files re-exported by child themes │ ├── lint-staged.js # lint-staged config — runs ESLint + Stylelint on staged files │ ├── prettier.js # Prettier config │ └── stylelint.js # Stylelint config │ └── gulp/ ├── environment.js # CLI flag parser — development / production / ci / watch / verbose ├── paths.js # Resolved src/dist/pubStatic paths from composer.json ├── collectEntries.js # Resolves webpack entry points across theme inheritance chain ├── collectParents.js # Walks theme.xml chain → ordered list of parent paths ├── parentAliases.js # Builds webpack alias map (e.g. Creativeshop → parent src/) ├── skipUnchangedPlugin.js # Webpack plugin — skips emitting assets identical to dist ├── imageminStream.js # Gulp stream that runs images through imagemin plugins ├── imageminSharpJpeg.js # Imagemin plugin — JPEG compression with sharp's mozjpeg encoder ├── imageminSharpPng.js # Imagemin plugin — PNG palette compression with sharp's libimagequant ├── srcExists.js # Guards gulp.src() calls — prevents ENOENT when optional dirs are absent │ ├── config/ # Per-task configuration │ ├── browserSync.js # BrowserSync proxy settings and all rewrite middleware │ ├── buildSprites.js # SVG sprite generation settings │ ├── buildWebpack.js # Full webpack configuration (entries, loaders, plugins, cache) │ ├── clean.js # Paths deleted by the clean task │ ├── cleanCache.js # Magento cache types + connection config (ssh/local/docker) │ ├── collectViewXml.js # Source paths for view.xml collection │ ├── copyDocs.js # Glob patterns for documentation assets │ ├── copyHtml.js # Glob patterns for HTML templates │ ├── copyImages.js # Glob patterns + imagemin plugin options │ ├── copyScripts.js # Glob patterns for plain JS vendor scripts │ └── copyUnchanged.js # Glob patterns for all other static assets │ └── tasks/ # Individual gulp task implementations ├── browserSync.js ├── buildWebpack.js ├── clean.js ├── cleanCache.js ├── cleanWebpackCache.js ├── collectViewXml.js ├── copyDocs.js ├── copyHtml.js ├── copyImages.js ├── copyScripts.js ├── copyUnchanged.js ├── eslint.js ├── generateCerts.js └── stylelint.js ``` * * * ## 主题继承制度 构建者支持多层次的主题继承. 文件解析度走满 `theme.xml` 构建时间的父链 : ``` theme-creativeshop (base) └── theme-child └── theme-grandchild ``` 任一文件的解析命令 : 1. 当前主题 `src/` 2. 父主题 `src/` 3. 基础主题 `src/` (主题编剧) 4. `node_modules/` Webpack别名和模块解析路径从这个链中自动被接通——儿童主题不需要手动路径配置. ### 父主题设置 每个主题都声明其母于 `src/theme.xml`数字 : ```xml Child Theme Creativestyle/theme-creativeshop ``` 构建者读取了这个文件来构建异名映射并解决跨链条所有级别的出入口. * * * ## 主题整合 主题通过 `gulpfile.mjs`数字 : ```js import gulp from 'gulp'; import registry from '@creativestyle/magesuite-frontend-builder'; gulp.registry(registry); ``` 要覆盖 Webpack 配置,请添加一个 `webpack.config.js` 到您的主题根 —— 它将随着底部配置通过 `webpack-merge`。 。 。 . ### 儿童主题 `package.json` ```json { "scripts": { "menu": "magesuite-menu", "build": "gulp build --env production", "build:verbose":"gulp build --env production --verbose", "serve": "gulp serve", "start": "gulp serve", "lint:js": "gulp eslint", "lint:css": "gulp stylelint", "lint": "gulp eslint && gulp stylelint", "prepare": "husky" }, "resolutions": { "caniuse-lite": "^1.0.30001781" } } ``` ### 儿童主题 `tsconfig.json` ```json { "compilerOptions": { "target": "ES2022", "module": "commonjs", "moduleResolution": "node", "noEmit": true, "skipLibCheck": true, "paths": { "*": ["./src/*", "./node_modules/*", "../theme-creativeshop/src/*"] } } } ``` ### 儿童主题 `src/declarations.d.ts` ```typescript declare module '*.scss'; declare module 'mage/*'; ``` TypeScript 对 SCSS 导入或 Magento 的要求JS 模块没有内置的理解, 因此没有此文件 `tsc` (和ESLint TypeScript 解析器)会错误于: - `import '*.scss'` ——主题TS文件常导入SCSS;TypeScript将未知扩展作为缺失模块. - `import ... from 'mage/translate'` - 马根托核心船 `.d.ts` 文档,所以 `mage/*` 进口是未解决的类型. 文件在不触及任何主题源文件的情况下,将两种错误压制在全球. * * * ## 发展工作流程 ### 开始发展 ```bash # Install dependencies yarn install # Start the development server yarn serve ``` 浏览器Sync在Magento前启动一个倒置代理. CSS更改是在不重新加载页面的情况下被注入;JS更改会触发重新加载. SSL 是通过 mkcert 自动处理的 — 见 [现场 SSL CERT.md](https://npmcn.com/package/%40creativestyle/magesuite-frontend-builder/LOCAL_SSL_CERT.md)。 。 。 . ### 生产建设 ```bash yarn build # concise summary output yarn build:verbose # full asset list with sizes and all warnings ``` ### 线性 ```bash yarn lint # ESLint + Stylelint yarn lint:js # ESLint + tsc --noEmit yarn lint:css # Stylelint # Auto-fix formatting and fixable violations yarn gulp eslint --fix yarn gulp stylelint --fix ``` 承诺前的钩子(Husky + lint-staged)在每次承诺前都会自动地在已上演的文件上运行ESLint和Stylelint. * * * ## 交互式菜单 `yarn menu` 打开带有每个项目描述的箭键可导航发射器。 不需要记住命令名称. ### 添加到主题中 ```json "scripts": { "menu": "magesuite-menu" } ``` 二进制自动通过 `bin` 字段中的字段 `package.json`。 。 。 . ### 菜单组 | 组 | 图标 | | --- | --- | | **构建** | `build`, (中文(简体) ), `build:verbose`, (中文(简体) ), `serve` | | **林特** | `lint`, (中文(简体) ), `lint:js`, (中文(简体) ), `lint:css`, (中文(简体) ), `lint --fix`, (中文(简体) ), `lint:js --fix`, (中文(简体) ), `lint:css --fix` | | **公用事业** | `cleanWebpackCache`, (中文(简体) ), `pre-commit` | * * * ## TypeScript 编译管道 类型脚本由 **`ts-loader`** 在 Web 软件包内 `transpileOnly: true` ——字条类型并释放出JavaScript但跳过类型检查. 这让时间变得很快. 类型检查由 **`tsc --noEmit`**,它与 ESLint 期间同时运行 `yarn lint:js`数字 : ``` yarn build → Webpack + ts-loader (transpileOnly: true) → fast, no type errors surfaced yarn lint:js → tsc --noEmit + ESLint → type errors and lint violations reported ``` 承诺前的钩子运行 **仅将 ESLint 放在已播放的文件** -没有 `tsc`。类型错误不阻断输入;它们通过 `yarn lint:js` (原始内容存档于2018-03-26). 或CI. * * * ## `resolutions` - 罐头油 添加一个 `resolutions` 字段到子主题 `package.json`数字 : ```json "resolutions": { "caniuse-lite": "^1.0.30001781" } ``` `caniuse-api` (自动前置器的过渡依赖) `caniuse-lite@^1.0.0` ——一个松散的范围,它决定了一个僵硬的版本,在每个建筑上触发"浏览器数据是N个月的"警告. 这个 `resolutions` 字段崩溃全部嵌入 `caniuse-lite` 条目为: `yarn.lock`。 。 。 . 运行 `yarn install --force` 在添加字段以应用决议后. * * * ## 软件包参考 ### 构建管弦乐 | 软件包 | 目的 | | --- | --- | | `gulp` 五进制 | 任务执行者和管道管线员 | | `undertaker-registry` | 允许主题通过 `gulp.registry()` | | `yargs` | CLI 参数解析( E)`--env`, (中文(简体) ), `--verbose`, (中文(简体) ), `--fix`, (中文(简体) ), `--watch`(中文(简体) ) | | `fancy-log` | 在所有任务中使用的时间戳控制台输出 | | `plugin-error` | 任务失败报告的结构化 gulp 错误对象 | | `chalk` | 终端颜色输出——用于构建横幅和警告消息 | ### 网络包装和联署材料捆绑 | 软件包 | 目的 | | --- | --- | | `webpack` 五进制 | 模块捆绑器 — 编译 TypeScript 入口, 捆绑 SCSS | | `webpack-merge` v6 数据 | 深层儿童主题 `webpack.config.js` 覆盖到基础配置 | | `ts-loader` | 用于 TypeScript 转接的 Webpack 装入器(`transpileOnly` 模式) | | `typescript` | TypeScript 编译器( 由 ts- loader 使用) | | `@types/jquery` | JQuery 类型定义(全球马根托) | | `@types/requirejs` | 要求JS 类型定义( 用于 Magento 模块覆盖) | | `glob` 页:1 | 解决跨主题继承链的入门点文件模式 | ### CSS 处理 | 软件包 | 目的 | | --- | --- | | `sass` | Dart Sass 编译器 — 将 SCSS 编译为 CSS | | `sass-loader` 第17个 | 引用 Dart Sass 的 Webpack 加载器 | | `css-loader` ưμ㼯a | 决定CSS `@import` 财务报告和审定财务报表 `url()` 网包内 | | `mini-css-extract-plugin` | 将 CSS 编译为单独的摘录 `.css` 每个输入点的文件 | | `css-minimizer-webpack-plugin` | 改进生产建筑中提取的CSS | | `postcss-loader` 页:1 | 在编译的 CSS 上运行 PostCSS 插件 | | `autoprefixer` | PostCSS插件 — 根据浏览器列表目标添加供应商前缀 | | `postcss-flexbugs-fixes` | PostCSS 插件 — 跨越浏览器补丁已知的 Flexbox 错误 | ### 资产处理 | 软件包 | 目的 | | --- | --- | | `gulp-changed` | 跳过复制自上次构建以来没有更改的文件 | | `imagemin` 数字 9 | 图像优化核心, 运行于构建者自己的 `gulp/imageminStream.js` (仅生产) | | `sharp` 页:1 | 通过mozjpeg编码器进行Lossy JPEG压缩,而通过libimagequant调色板 quantiser进行Lossy PNG压缩,两者都用锐口捆绑. 每个平台都建有土生土长的船,所以没有下载 `yarn install` 在苹果硅上不需要罗塞塔 | | `imagemin-svgo` 第10个 | 通过 svgo v2 实现 SVG 优化 | | `del` 页:1 | 删除文件和目录 | ### 定型和格式化 | 软件包 | 目的 | | --- | --- | | `eslint` 第10个 | JavaScript 和 TypeScript linter – 平面配置格式 ()`eslint.config.js`(中文(简体) ) | | `@eslint/js` | ESLint的内置建议 JS规则集 | | `typescript-eslint` | TypeScript-aware 规则和 TS 解析器 | | `prettier` | 对物质的意见代码——通过ESLint和Stylelint强制执行 | | `eslint-config-prettier` | 禁用与 Prettier 相冲突的 ESLint 格式化规则 | | `eslint-plugin-prettier` | 将 Pretier 作为 ESLint 规则运行 | | `stylelint` 第17个 | SCSS 接口 | | `stylelint-scss` | SCSS 特有规则 | | `stylelint-config-recommended-scss` | 建议的常设委员会规则 | | `stylelint-prettier` | 将 Pretier 作为样式林规则运行 | | `postcss-scss` | 用于解析 SCSS 的 PostCSS 语法( 由 Stylelint 要求) | ### 交互式菜单 | 软件包 | 目的 | | --- | --- | | `@clack/prompts` | 终端 UI 组件 - `intro`, (中文(简体) ), `outro`, (中文(简体) ), `select`, (中文(简体) ), `log` | | `@clack/core` | 未被描述的即时原始人—— `SelectPrompt` 用于自定义 Ctrl+C 取消行为 | ### 巨钩 | 软件包 | 目的 | | --- | --- | | `husky` 数字 9 | 管理 git 钩子 —— 运行在承诺前的 Lint- staged | | `lint-staged` 第17个 | 只运行在已播放的文件上的 linters | * * * ## V 5.0 vs 4.x中的变化 ### 通过 | 区域 | 变动 | | --- | --- | | **网络包装 v5** | 已替换 Webpack v4. 内置文件系统缓存替换 `cache-loader` ——加快增量建设 | | **CSS 微调** | `css-minimizer-webpack-plugin` 替换已贬值 `optimize-css-assets-webpack-plugin` | | **本地无害环境管理** | 由CJS转换为本地ES模块的构建器(`"type": "module"`) (中文(简体) ). 全体 `require()` 编号 : `module.exports` 替换为 `import` 编号 : `export default` | | **无害环境管理一揽子措施** | `del`, (中文(简体) ), `glob`, (中文(简体) ), `gulp`, (中文(简体) ), `gulp-imagemin`, (中文(简体) ), `imagemin-*` 仅限无害环境管理;现已静态进口 | | **`MagesuiteRegistry` 类** | 从ES5实现现代化 `util.inherits` + 原型模式到ES6 `class extends DefaultRegistry` | | **ESLint v10 平面配置** | 从 `.eslintrc.js` 遗留配置到 `eslint.config.js` 平面配置格式 | | **达特萨斯 1.x** | `sass-loader` v16 自动探测达特萨斯; `implementation: sass` 删除选项 | | **浏览器Sync v3** | 配备 URL 重写、 cookie 域修正、 CSP 剥离和 POST 机体重写 Magento 链接掩码兼容性 | | **Verbose 构建输出** | `--verbose` 旗帜显示完整的资产大小和警告; 默认构建只显示一个简明摘要行 | | **交互式菜单** | `magesuite-menu` 二进制-箭键可导航命令发射器 | ### 故意压制——为什么 | 取缔 | 原因 | Devs应该适应吗? | | --- | --- | --- | | **资产贬值** (单位:千美元)`import`, (中文(简体) ), `global-builtin`, (中文(简体) ), `slash-div`, (中文(简体) ), `color-functions`, (中文(简体) ), `if-function`(中文(简体) ) | 允许尚未迁移到 `@use`编号 :`@forward` 以编译干净. | 一旦所有主题通过 `mgs-migrate-sass`。 。 。 . | | **Webpack 性能提示** dev/观察模式 | 细化前资产大小毫无意义 | 没有 - 提示在 `yarn build` 并完全进入 `yarn build:verbose` | | **`imagemin-gifsicle`** 完全放弃 | 二进制安装器与节点18+不相容;包自2019起未保存 | 否 —— 全球IF 资产复制不优化 | | **`@typescript-eslint/no-explicit-any`** 关 | 主题代码库已普及 `any` 使用量 | **对** 逐步替换 `any` 包含新代码中的适当类型 | * * * ## 解决问题 ### CSS 不通过浏览器注入Sync - 校验您正在访问浏览器Sync URL(带有端口),而不是直接访问 Magento URL - 检查代理目标 `gulp/config/browserSync.js` 匹配您的本地域 - 确保 CSS 文件生成正确无误 `web/css/` 目录 ### “ 未找到模块” 错误 - 检查 `tsconfig.json` `paths` ——母主题路径必须与实际相对位置相匹配 - 校验父主题在 `vendor/creativestyle//` - 运行 `yarn install` 以确保安装所有构建者的依赖性 ### 分支切换后 Stale 网络包缓存 ```bash yarn gulp cleanWebpackCache ``` 在切换有主要配置差异的分支后或更改了webpack别名后运行此功能——持久的缓存不会自动检测出别名的更改. ### `[DEP0060] util._extend` 折旧期间 `yarn serve` **原因 :** 浏览器同步取决于 `http-proxy` (自2020年以来未保留)使用已贬值的 `util._extend` API. 地平面在节点.js 22+. **影响 :** 无 - `yarn serve` 工作没错 只有化妆的噪音。 上游打开 : [浏览器同步 第2091期](https://github.com/BrowserSync/browser-sync/issues/2091)。 。 。 . * * * ## 进一步阅读 - [变动情况](https://npmcn.com/package/%40creativestyle/magesuite-frontend-builder/CHANGELOG.md) ——版本历史 - [现场 SSL CERT.md](https://npmcn.com/package/%40creativestyle/magesuite-frontend-builder/LOCAL_SSL_CERT.md) – 为浏览器Sync 设置本地 HTTPS ## 常见问题 ### @creativestyle/magesuite-frontend-builder 是什么？ Magento 2 / MageSuite主题的现代构建系统 网页包 5, \(中文\(简体\) \), 类型脚本,以及 纸浆5\. 提供 Webpack 捆绑,SCSS 编译,资产复制,图像优化,linting,浏览器Sync Dev 代理,以及 Magento 缓存管理- a ### 如何安装 @creativestyle/magesuite-frontend-builder？ 在项目目录运行 npm install @creativestyle/magesuite-frontend-builder，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 magesuite-menu，可以用 npx magesuite-menu 直接运行。 ### @creativestyle/magesuite-frontend-builder 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/creativestyle\_\_magesuite-frontend-builder 是否存在。 ### @creativestyle/magesuite-frontend-builder 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @creativestyle/magesuite-frontend-builder 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.22\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @creativestyle/magesuite-frontend-builder 可以商用吗？ @creativestyle/magesuite-frontend-builder 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @creativestyle/magesuite-frontend-builder 的下载量有多少？ 根据 npm 官方下载统计，@creativestyle/magesuite-frontend-builder 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,280 次，日均约 76 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @creativestyle/magesuite-frontend-builder 还在维护吗？ 最新版本 5\.1\.0 发布于 2026/10/21（20 天前）；至今共发布 71 个版本，其中过去 12 个月发布了 4 个；首次发布于 2018/11/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。