# @apostrophecms/vite 中文文档
规范地址：https://npmcn.com/package/%40apostrophecms/vite/
版本：1\.2\.0
npm 元数据更新时间：2026-10-20T16:57:54.528Z
中文译文更新时间：2026-11-06T11:07:57.148Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40apostrophecms/vite
原文对照：https://npmcn.com/package/%40apostrophecms/vite/?lang=original
项目主页：https://github.com/apostrophecms/apostrophe/tree/main/packages/vite#readme
源码仓库：https://github.com/apostrophecms/apostrophe
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：120 kB，41 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2024-10-31T14:21:32.460Z
- 最新版本发布：2026-09-30T19:29:33.739Z
- 近 30 天下载量：4326（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 4 个）
## 中文简介
用于ApospropheCMS项目的维特构建流.
## 安装
```sh
npm install @apostrophecms/vite
```
也可以使用：`pnpm add @apostrophecms/vite`、`yarn add @apostrophecms/vite`、`bun add @apostrophecms/vite`
## README
# Aposrophe Vite Bundling 和 HMR 软件厂
[](https://docs.apostrophecms.org/)[ ](http://chat.apostrophecms.org/)[](https://github.com/apostrophecms/vite/blob/main/LICENSE.md)
这一扩展为ApostropeCMS项目提供了Vite集成,使模块在开发过程中被捆绑并被热模块所取代.
## 安装
要安装模块, 请使用命令行在 Aposrope 项目的根目录中运行此命令 :
```
npm install @apostrophecms/vite
```
## 使用量
将模块添加到 `app.js` 文件 :
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
}
});
```
## 配置
## 热模块替换配置
默认情况下, HMR 被启用为您的项目的公共 UI 代码 。 所有配置都通过ApostropeCMS的核心资产模块选项处理,简化了设置和维护.
### 启用管理 UI HMR
对于ApostropeCMS 管理员界面的开发工作,您可以切换HMR,以瞄准管理员UI而不是公交组件:
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
hmr: 'apos', // 'public' targets the project UI (default)
},
},
}
});
```
### 禁用 HMR
您可以在不需要或不需要时禁用热模块替换, 同时仍然使用 Vite 构建 :
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
hmr: false,
},
},
}
});
```
## 更改基本 Websocket 服务器端口
在开发过程中,热模块重载(HMR)服务器使用WebSocket并运行在与你的ApostropeCMS实例相同的端口上. 对于高级配置,您可以通过设置开发服务器作为独立的HTTP服务器在不同的端口运行 `hmrPort` 选项。 当您需要避免端口冲突或使用特定的网络配置时,此功能可能有用 :
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
hmrPort: 3001,
},
},
}
});
```
## 启用生产中的源地图
您可以启用生产中的源地图来帮助调试已修改的代码并查看浏览器 DevTools 中的原始源文件. 虽然这略微地增加了初始下载大小,但对调试出产问题很有价值.
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
productionSourceMaps: true,
},
},
}
});
```
## 仅在启用 HMR 时才输入代码
如果您想要仅在开发模式和HMR启用时在您的站点中注入一些代码,则您可以使用 Aposrophe nunjucks 组件.
```njk
{# module-name/views/myComponent.html #}
```
```js
// 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'
});
}
};
```
当组件出现时, 选项控制 :
```javascript
when: 'hmr' // Only visible when HMR is active
when: 'dev' // Visible in any development mode
when: 'prod' // Only visible in production
```
捆绑者选项允许您指定哪个捆绑者必须活动才能显示组件 :
```javascript
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/` 目录.
```javascript
// 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/` 路径的一部分.
```javascript
// 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框架代码中导入:
```javascript
// 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 :
```scss
/* You can use aliases to import assets */
/* Actual path: modules/some-module/ui/scss/_styles.scss */
@use '@/some-module/scss/styles';
```
Vue JS支持直接从模板中导入资产:
```vue
```
在其他框架中(但也在Vue),您可以使用 `import` 提及资产的语句:
```jsx
import logo from '@/some-module/assets/logo.svg';
function MyComponent() {
return 
;
}
```
CSS URL可以通过两种方式解决. 您可以使用 Aposrope 文档中的文档 `some-module/public` 文件夹和 `/modules/some-module/font.ttf` 您的文件所在的 URL `./modules/some-module/public/font.ttf`
```css
@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` 目录。 这是维特用来解决路径和构建工程的根.
```css
@font-face {
font-family: Inter;
src: url("/src/some-module/fonts/font.ttf") format("truetype");
}
```
同样的规则适用于 `url()` cSS文件中的函数.
## 配置您的代码编辑器
每个编辑,都明白 `jsconfig.json` 或者说 `tsconfig.json` 文件,可以配置以了解 `@/` 本单元提供的别名。 举个例子 `jsconfig.json` 可以在工程根中放置的文件 :
```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 设置 :
```javascript
// 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 配置工具:
```javascript
// apos.vite.config.js
import { defineConfig } from '@apostrophecms/vite/vite';
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [ vue() ]
});
```
配置格式遵循标准 [虚拟配置选项](https://vitejs.dev/config/)。常见的使用案例包括添加插件,定义环境变量,以及自定义构建设置.
> 注:所有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进口的前缀
```css
/* 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 是什么？
用于ApospropheCMS项目的维特构建流\.
### 如何安装 @apostrophecms/vite？
在项目目录运行 npm install @apostrophecms/vite，或使用 pnpm add / yarn add / bun add。
### @apostrophecms/vite 支持 TypeScript 吗？
该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apostrophecms\_\_vite 是否存在。
### @apostrophecms/vite 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @apostrophecms/vite 可以商用吗？
@apostrophecms/vite 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @apostrophecms/vite 的下载量有多少？
根据 npm 官方下载统计，@apostrophecms/vite 在 2026/10/07 – 2026/11/05 这 30 天内被下载 4,326 次，日均约 144 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @apostrophecms/vite 还在维护吗？
最新版本 1\.2\.0 发布于 2026/10/01（1 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 4 个；首次发布于 2024/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。