网站导航
集成

在 Nuxt 中配置 Master CSS

通过 Nuxt 加载项目 CSS 入口，并验证静态样式、浏览器生成或 Nitro 响应渲染。

本页内容

安装 Master CSS Nuxt 模块，并通过 Nuxt 的 css 选项加载 CSS 入口。模块会处理 CSS 交付，不会改变 Nuxt 的 HTML 渲染模式。

#安装

  1. #添加 Master CSS

    在现有的 Nuxt 项目中，从项目根目录运行安装程序。默认使用静态模式：扫描完整的类名字符串，并输出普通 CSS。

    npm create @master/css@2.0.0 -- --framework nuxt --yes

  2. #加载项目样式表

    保留模块注册，并显式加载安装程序创建的 CSS 入口。~~/ 指向项目根目录，即使 Nuxt 项目的应用目录为 app/ 也一样。

    nuxt.config.ts
    export default defineNuxtConfig({  modules: [['@master/css-nuxt', { mode: 'static' }]],  css: ['~~/assets/css/master.css']})
    assets/css/master.css
    @import '@master/css';

  3. #开始使用 Master CSS

    启动开发服务器，为第一个组件应用样式。这些示例使用 Nuxt 4 的 app/ 目录。

    4. 检查已安装的样式

    app/app.vue
    <template>  <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">    Hello World  </p></template>
    中性色表面、细边框、小圆角，以及四边各 1rem 的内边距。

#检查配置

开发服务器运行时，将 app/app.vue 中的 p-md 改为 p-lg：内边距应从 1rem 增加到 1.5rem。恢复原值后，构建并提供应用。使用 Nuxt 默认的 Node 服务器预设时：

npm run buildnode .output/server/index.mjs

如果使用其他 Nitro 部署预设，请遵循其服务启动流程。启用 Nuxt SSR 时，禁用 JavaScript 并重新加载：段落应保留内边距、圆角和凸起表面。静态描述的是 CSS 生成方式，不会将仅在客户端运行的 Nuxt 页面变成服务器渲染页面。

如果页面没有样式，先确认 css 选项加载了根样式表，再检查模块是否只注册一次。在已加载的 CSS 中查找 .p-md；仅构建成功并不能证明入口已传递到页面。

#选择其他渲染模式

默认使用静态模式。安装程序选项会设置模块的 mode；切换模式时，请保留 CSS 入口：

模式安装程序选项交付方式
静态无扫描源代码后生成的样式表
运行时--mode runtime浏览器运行时，不提供服务器端初始页面 CSS
渐进式--mode progressiveNitro 提供首次响应 CSS，再交由运行时接管
在浏览器中生成新类名
npm create @master/css@2.0.0 -- --framework nuxt --mode runtime --yes

安装程序会注册 ['@master/css-nuxt', { mode: 'runtime' }]。启用 SSR 时，Nuxt 仍会在服务器渲染 HTML，而运行时则在浏览器中提供生成的类名规则。构建并提供 Nitro 输出后，在浏览器控制台运行：

document.querySelector('#master-check').classList.add('underline')

无需重新构建，段落就应出现下划线。如果没有，请检查运行时程序的请求和控制台诊断信息。

包含服务器渲染的样式
npm create @master/css@2.0.0 -- --framework nuxt --mode progressive --yes

渐进式模式会为正文为字符串的 Nitro HTML 响应加入首次响应 CSS；流式正文不会转换。先禁用 JavaScript 检查初始样式，再按上述方式测试页面 manifest 中没有包含的后续类名。

还请在目标目录测试复制后的部署产物：仅在原位构建，无法证明所有 manifest 和程序路径都可迁移。如果复制后的服务器报告原项目 node_modules/.master-css/manifest/ 下的 ENOENT 路径错误，说明它仍依赖构建机器上的 manifest，尚不能独立部署。如果静态或运行时模式能满足应用的交付需求，请改用其中一种，并在移动输出后再次验证。