@apostrophecms/vite

中文文档

1.2.0发布于 2026/10/01MITESM + CJS近 30 天下载 4326

用于ApospropheCMS项目的维特构建流.

文档目录24 节

安装
使用量
配置
热模块替换配置
启用管理 UI HMR
禁用 HMR
更改基本 Websocket 服务器端口
启用生产中的源地图
仅在启用 HMR 时才输入代码
提供了 Vite 配置
预配置的异名
进口静态资产和气体
配置您的代码编辑器
扩展虚拟配置
1. 通过任何模块 build.vite 财产
2. Via 项目配置文件
限制和已知问题
热模块替换
公共资产
维特异形解析器
移徙准则
导入路径
ApostropheCMS 磁带控制系统模块导入
模块系统

Aposrophe Vite Bundling 和 HMR 软件厂

这一扩展为ApostropeCMS项目提供了Vite集成,使模块在开发过程中被捆绑并被热模块所取代.

安装

要安装模块, 请使用命令行在 Aposrope 项目的根目录中运行此命令 :

npm install @apostrophecms/vite

使用量

将模块添加到 app.js 文件 :

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/vite': {},
  }
});

配置

热模块替换配置

默认情况下, HMR 被启用为您的项目的公共 UI 代码。所有配置都通过ApostropeCMS的核心资产模块选项处理,简化了设置和维护.

启用管理 UI HMR

对于ApostropeCMS 管理员界面的开发工作,您可以切换HMR,以瞄准管理员UI而不是公交组件:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/vite': {},
    '@apostrophecms/asset': {
      options: {
        hmr: 'apos', // 'public' targets the project UI (default)
      },
    },
  }
});

禁用 HMR

您可以在不需要或不需要时禁用热模块替换, 同时仍然使用 Vite 构建 :

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/vite': {},
    '@apostrophecms/asset': {
      options: {
        hmr: false,
      },
    },
  }
});

更改基本 Websocket 服务器端口

在开发过程中,热模块重载(HMR)服务器使用WebSocket并运行在与你的ApostropeCMS实例相同的端口上. 对于高级配置,您可以通过设置开发服务器作为独立的HTTP服务器在不同的端口运行 hmrPort 选项。当您需要避免端口冲突或使用特定的网络配置时,此功能可能有用 :

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/vite': {},
    '@apostrophecms/asset': {
      options: {
        hmrPort: 3001,
      },
    },
  }
});

启用生产中的源地图

您可以启用生产中的源地图来帮助调试已修改的代码并查看浏览器 DevTools 中的原始源文件. 虽然这略微地增加了初始下载大小,但对调试出产问题很有价值.

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/vite': {},
    '@apostrophecms/asset': {
      options: {
        productionSourceMaps: true,
      },
    },
  }
});

仅在启用 HMR 时才输入代码

如果您想要仅在开发模式和HMR启用时在您的站点中注入一些代码,则您可以使用 Aposrophe nunjucks 组件.

{# module-name/views/myComponent.html #}
<!-- Shown only when HMR is enabled and in development mode. -->

// module-name/index.js
module.exports = {
  components(self) {
    return {
      myComponent(req, data) {
        return {};
      }
    };
  },
  init(self) {
    self.apos.template.prepend({
      where: 'head',
      when: 'hmr',
      bundler: 'vite',
      component: 'module-name:myComponent'
    });
  }
};

当组件出现时, 选项控制 :

when: 'hmr'   // Only visible when HMR is active
when: 'dev'   // Visible in any development mode
when: 'prod'  // Only visible in production

捆绑者选项允许您指定哪个捆绑者必须活动才能显示组件 :

bundler: 'vite'    // Only visible when using Vite
bundler: 'webpack' // Only visible when using webpack

您可以结合这些选项来精确控制您的组件出现时。例如,仅在使用具有HMR活性的Vite时显示组件,您将同时使用 when: 'hmr' 财务报告和审定财务报表 bundler: 'vite'。。。 .

提供了 Vite 配置

虽然 apos 构建(生活在ui/apos/ 每个模块的目录)已完全预配置,不允许定制 public 构建(在 ui/src/ )完全可自定义,并包含一个最小的配置来启动您 :

一个 PostCSS 插件处理核心特性, 如“ 断点预览 ” (在启用时)
Modules/ 别名以简化同一构件内的模块
@/ 化名,允许方便地访问跨模块和跨构建源代码

预配置的异名

这个 Modules/ 用于公共和管理的 UI 构建的化名,并允许您在不担心相对路径的情况下导入您的工程模块,但限制您仅使用其中的源 ui/src/ 目录.

// Current file: modules/another-module/ui/src/index.js
// Actual import path: modules/some-module/ui/src/lib/utils.js
import utils from 'Modules/some-module/lib/utils.js';

@/ 用于公共和行政管理 UI 架构的化名,并允许您从整个工程源代码导入文件。它遵循与您原始源代码相同的路径, 但跳过 ui/ 路径的一部分.

// Current file: any file in any module inside of the `ui/` folder
// Actual path: modules/some-module/ui/src/lib/utils.js
import utils from '@/some-module/src/lib/utils.js';

// Actual path: modules/some-module/ui/apos/mixins/SomeMixin.js
import SomeMixin from '@/some-module/apos/mixins/SomeMixin.js';

警告: 您可以访问 public b. 建议 apos 构建,反之亦然 @/ 别名。你应该谨慎使用,因为这可能导致进口问题得不到正确解决。如果导入的文件( 或其深度导入) 包含 Modules/ 异名进口。另一方面, @/ 更方便开发者,允许自动补全,且更直观可读. 确保包含您当前建筑中的大部分来源,并确保不包含输入来源 Modules/ 在从另一建筑物交叉进口时别名进口.

进口静态资产和气体

我们将Vite与AposfropeCMS集成的方式现在允许直接进口(包括动态进口)图像,字体等资产和其他文件. 您可以直接从您的香草JS/JS框架代码中导入:

// You can use aliases to import assets or a relative path when in the same module.
// Actual path: modules/some-module/ui/assets/logo.svg
import logo from '@/some-module/assets/logo.svg';
// Logo now contains the path to the image and will be normalized and correctly
// injected when building the project for production.

您也可以导入 Sass :

/* You can use aliases to import assets */
/* Actual path: modules/some-module/ui/scss/_styles.scss */
@use '@/some-module/scss/styles';

Vue JS支持直接从模板中导入资产:

<template>
  <img src="@/some-module/assets/logo.svg" alt="My logo" />
</template>

在其他框架中(但也在Vue),您可以使用 import 提及资产的语句:

import logo from '@/some-module/assets/logo.svg';

function MyComponent() {
  return <img src={logo} alt="My logo" />;
}

CSS URL可以通过两种方式解决. 您可以使用 Aposrope 文档中的文档 some-module/public 文件夹和 /modules/some-module/font.ttf 您的文件所在的 URL ./modules/some-module/public/font.ttf

@font-face {
  font-family: MyFont;
  src: url("/modules/some-module/font.ttf") format("truetype");
}

或者可以使用绝对源根路径 /src/some-module/fonts/font.ttf 文件位于 ./modules/some-module/ui/fonts/font.ttf。您可以检查您在中心位置复制的项目的来源 apos-build/@postrophecms/vite/default 目录。这是维特用来解决路径和构建工程的根.

@font-face {
  font-family: Inter;
  src: url("/src/some-module/fonts/font.ttf") format("truetype");
}

同样的规则适用于 url() cSS文件中的函数.

配置您的代码编辑器

每个编辑,都明白 jsconfig.json 或者说 tsconfig.json 文件,可以配置以了解 @/ 本单元提供的别名。举个例子 jsconfig.json 可以在工程根中放置的文件 :

{
  "compilerOptions": {
    "baseUrl": "./apos-build/@apostrophecms/vite/default",
    "paths": {
      "@/*": ["./src/*"]
    },
    "module": "ESNext",
    "moduleResolution": "bundler"
  },
  "exclude": [
    "apos-build/@apostrophecms/vite/default/dist",
    "node_modules",
    "public",
    "data"
  ]
}

注意: 如果您更改了您的项目资产命名空间, 您必须调整 baseUrl 财务报告和审定财务报表 exclude 路径。例如,如果您的工程名称空间是 my-namespace,则 baseUrl 应该是 ./apos-build/@apostrophecms/vite/my-namespace 编辑 exclude 路径 - apos-build/@apostrophecms/vite/my-namespace/dist。。。 .

注意: 如果您跟随编辑器中的导入( 如 Ctrl + 在 VSCode 中点击) , 它将会导致 apos-build 目录和NOT 原始源代码。这是因为 apos-build 目录包含所有模块(本地和npm)中整个项目源代码(包括Admin UI)的副本,是Vite用于构建项目的实际源代码.

扩展虚拟配置

您可以为您的 ApospropheCMS 项目自定义 Vite 配置 :

1. 通过任何模块 `build.vite` 财产

使用此方法在 AposropeCMS 模块中配置 Vite 设置 :

// modules/some-module/index.js
module.exports = {
  build: {
    vite: {
      myViteConfig: {
        // Standard Vite configuration
        define: {
          __MY_ENV__: '1',
        },
      }
    },
  },
};

2. Via 项目配置文件

对于全工程的Vite配置,请在您的工程根中创建其中之一 :

apos.vite.config.js (用于无害环境管理项目)
apos.vite.config.mjs (用于共同JS项目)

这种方法支持完整的Vite配置 API,并适用于您工程的UI构建. 您可以直接从 ApospropheCMS Vite 模块导入 Vite 配置工具:

// apos.vite.config.js
import { defineConfig } from '@apostrophecms/vite/vite';
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [ vue() ]
});

配置格式遵循标准虚拟配置选项。常见的使用案例包括添加插件,定义环境变量,以及自定义构建设置.

注:所有Vite配置相继合并——首先跨模块合并(遵循模块注册顺序,后期模块优先),最后与项目配置文件合并,最终优先.

限制和已知问题

热模块替换

HMR 只监视现有 anyModule/ui 目录. 如果添加一个新的 ui 模块的目录,重新启动服务器以启用该模块的HMR。默认使用 ApostropeCMS 启动套件 nodemon,简单键入 rs 在终端中按 Enter.
这个 apos HMR不会起作用的 public 构建包含 Vue 源(由 @vitejs/plugin-vue 插件). 高频 public 建筑仍应如所预期地运作。问题在于该页面将包含两个Vue例(核心和反应性),目前不支持. 我们正在研究解决这个问题的办法.

公共资产

变动至 ui/public 目录不会触发 HMR 或页面重载, 因为需要重新启动进程
工作周期: 添加 ui/public/ 文件夹到您的 nodemon 监视列表在任意 nodemon.json 或者说 package.json
未来对该功能的支持将取决于用户需求

维特异形解析器

设置自定义时 resolve.alias 在 Vite 配置中,路径必须解决到适当的 apos-build/... 源代码而不是原始源代码
未来加强计划:我们将提供诱导(例如, {srcRoot})或函数参数(例如, aposRoot)简化正确的路径分辨率

移徙准则

导入路径

删除全部 ~ 来自CSS/Sass进口的前缀

/* Instead of: @import "~normalize.css" */
@import "normalize.css"

ApostropheCMS 磁带控制系统模块导入

建议: 使用 Modules/module-name/components/... 代替直接路径 apostrophe/modules/module-name/ui/apos/components/...
此别名仅用于 apos 源代码; 项目代码可以定义自己的别名

模块系统

在用户界面源代码中只使用无害环境管理语法 :
- ✅ import abc from 'xxx' 或者说 const abc = await import('xxx')
- ✅ export default ... 或者说 export something
- QQ 无普通JS : require(), (中文(简体) ), module.exports, (中文(简体) ), exports.xxx

版本与发布记录

@apostrophecms/vite 共发布 8 个版本，首次发布于 2024/10/31；过去 12 个月发布了 4 个版本。

版本	发布日期	距今
`1.2.0`latest	2026/10/01	1 个月前
`1.1.2`	2026/07/11	3 个月前
`1.1.1`	2025/11/26	11 个月前
`1.1.1-alpha.1`alpha	2025/11/11	11 个月前
`1.1.0`	2025/06/12	1.4 年前
`1.0.0`	2024/12/19	1.9 年前

其他发布通道：beta → 1.0.0-beta.1，alpha → 1.1.1-alpha.1。

关于 @apostrophecms/vite 的常见问题