企业官网建设流程全解析

• 前端
• UI组件

Nebular 是一套基于 Eva Design System 的可定制 Angular UI 组件库，本指南讲解在其当前仓库（@nebular/theme17.x）中完成安装的两种主流方式：通过 Angular Schematics 的ng add一键接入，以及在已有 Angular 工程中手动安装依赖、配置模块与样式。读完本文后，你将掌握 Nebular 主题模块、图标包、认证与安全模块的完整接入流程，并能根据项目情况选择预编译 CSS 或可定制 SCSS 主题方案。

安装方式概览

Nebular 提供两条接入路径，均以“已存在或即将创建的 Angular 应用”为前提：

如果你完全没有代码基础，建议先参考 Angular CLI 官方文档创建应用；如果你想基于 ngx-admin 启动模板起步，则可以阅读 基于 Starter Kit (ngx-admin) 安装 一文。本文只讲解如何将 Nebular 模块装入你自己的工程，不含 ngx-admin 专属的自定义组件（如 Temperature Widget、Dashboard 图表等）——若你需要复用这些组件，请先按本文完成 Nebular 接入，再拷贝所需组件到项目并注册到对应模块中。

方式一：使用 Angular CLI 接入（推荐）

安装 Angular CLI

Nebular 官方强烈推荐使用@angular/cli开发 Angular 应用，全局安装命令如下：

npm install -g @angular/cli

创建新项目

使用 Angular CLI 创建全新工程：

ng new my-new-project

执行 ng add 完成接入

Nebular 支持通过 Angular Schematics 完成初始化配置，只需一条命令即可完成整个接入流程：

ng add @nebular/theme

执行完毕后 Nebular 即可投入使用。从当前仓库的 Schematics 实现（ng-add 入口）可以看出，这条命令背后实际完成的工作远比“加一个依赖”多：

1. 写入 peer 依赖：installMainPeerDependencies会读取项目已有的@angular/core、@angular/cli版本，向package.json写入@angular/animations、@angular/cdk、@nebular/theme、@nebular/eva-icons等依赖；
2. 自动安装：通过NodePackageInstallTask触发npm install；
3. 顺序执行后续 Schematics：安装完成后依次运行post-install与setup，setup（setup.ts）再链式执行模块注册、主题注册、根组件布局包裹三个步骤。

之所以拆成“先安装再配置”，是因为后续的setup步骤内部依赖@angular/cdk/schematics与@schematics/angular工具包，必须先安装完成才能运行。

ng add 支持的配置选项

ng add @nebular/theme并非“一键到底”，它支持通过交互式提示或命令行参数控制安装行为。可配置项定义在 schema.json：

例如直接指定暗色主题并跳过布局包裹：

ng add @nebular/theme --theme dark --layout false

安装过程实际修改了什么

结合 模块注册实现 与 主题注册实现，ng add会对你的工程做如下改动：

• 动画模块：在根模块导入BrowserAnimationsModule（来自@angular/platform-browser/animations）；若项目已显式使用NoopAnimationsModule，则跳过并打印警告，避免运行时冲突；
• Nebular 模块：向根模块导入NbThemeModule.forRoot({ name: '主题名' })、NbLayoutModule与NbEvaIconsModule；
• 路由模块：若工程尚未导入RouterModule或AppRoutingModule，会自动生成app-routing.module.ts并注册；
• 主题样式：开启customization时生成themes.scss并在styles.scss中注入@use 'themes'与@nebular/theme/styles/globals；关闭时则把node_modules/@nebular/theme/styles/prebuilt/<theme>.css写入angular.json的 styles 数组，且会校验避免重复引入其他 Nebular 主题；
• 布局骨架：layout为true时，将AppComponent的模板（内联或 HTML 文件均可）包裹进<nb-layout>/<nb-layout-header>/<nb-layout-column>/<nb-layout-footer>结构中（见 wrap-in-layout 实现），这是 Nebular 组件正常工作的前提。

上述行为均有对应测试用例覆盖，可参考 ng-add 测试，其中验证了themes.scss与styles.scss的期望生成内容。

方式二：手动安装

如果你希望在已有 Angular 应用中逐步、可控地接入 Nebular，可按照以下步骤操作。此方式假设你已经创建好了一个 Angular 应用。

安装 Nebular 模块

npm install --save @nebular/theme @angular/cdk @angular/animations

从 @nebular/theme 的 package.json 可以看到，@nebular/theme将@angular/animations、@angular/common、@angular/core、@angular/router、@angular/cdk与rxjs声明为 peerDependencies，因此手动安装时需保证这些包的版本与当前仓库的 17.x 版本声明（对应 Angular 21）兼容；npm install会自动校验并在缺失时给出提示。

安装图标包（推荐）

从 Nebular 4.0 起，Eva Icons 是官方推荐的 SVG 图标库，可一并安装：

npm install --save eva-icons @nebular/eva-icons

@nebular/eva-icons模块的用法细节可参考仓库内的 eva-icons README 及 图标组件目录。

安装认证与安全模块（可选）

若你的应用需要登录认证与访问控制，可额外安装：

npm install --save @nebular/auth @nebular/security

认证模块的完整概念与安装说明见 Auth 模块简介 与 Auth 安装指南。

配置 Nebular

在应用根模块app.module.ts中引入主题模块：

import { NbThemeModule } from '@nebular/theme'; // ... @NgModule({ imports: [ // ... // 默认启用 default 主题；传入 { name: 'dark' } 可启用暗色主题 NbThemeModule.forRoot(), ], }) export class AppModule {}

从 NbThemeModule 实现 可以看出，forRoot()的完整签名是：

static forRoot( nbThemeOptions: NbThemeOptions = { name: 'default' }, nbJSThemes?: NbJSThemeOptions[], nbMediaBreakpoints?: NbMediaBreakpoint[], layoutDirection?: NbLayoutDirection, ): ModuleWithProviders<NbThemeModule>

• 第一个参数nbThemeOptions控制启用的主题名，内置可选值为default、dark、cosmic、corporate；
• 该方法同时注册主题服务、断点服务、滚动与标尺服务、方向服务、Spinner、Status 服务以及 Overlay 模块的 providers，并把主题选项通过NB_THEME_OPTIONS令牌提供给全局依赖注入；
• forRoot()只应在根模块调用一次，子模块中通常无需再次调用。

安装样式

接下来为工程引入 Nebular 的全局样式。最简单的做法是在angular.json的styles数组中加入预编译主题 CSS：

"styles": [ "node_modules/@nebular/theme/styles/prebuilt/default.css" ]

将default.css换成dark.css即可启用暗色主题。仓库 prebuilt 样式目录 中共有 9 个文件，覆盖四个内置主题及其 Custom Properties 变体：

这些文件的发布路径均在 @nebular/theme package.json 的 exports 声明 中予以导出。

可定制主题（SCSS 进阶方案）

本文描述的是基础样式安装。如果你需要更高级的特性——比如自定义主题变量，或运行时在多个主题间切换——建议参考 启用可定制主题 与 多运行时主题 两篇文章。

可定制方案要求项目启用 SCSS（ng add在非 SCSS 工程中启用customization时会直接抛出“Customizable theme requires scss”异常）。ng add生成的themes.scss骨架如下：

@forward '@nebular/theme/styles/theming'; @use '@nebular/theme/styles/theming' as *; @use '@nebular/theme/styles/themes/default'; $nb-themes: nb-register-theme(( // 在这里添加你的自定义变量，例如： // color-primary-100: #f2f6ff, // color-primary-500: #3366ff, // color-primary-900: #091c7a, ), default, default);

同时styles.scss会被注入全局样式安装代码：

@use 'themes' as *; @use '@nebular/theme/styles/globals' as *; @include nb-install() { @include nb-theme-global(); };

nb-install()与nb-theme-global()是 Nebular 样式体系提供的 Sass 入口，负责将注册的主题变量安装为组件可用的全局样式，是定制主题工作的基础。

安装后的下一步

完成上述任意一种安装后，即可着手创建你的第一个 Nebular 页面，可参考 创建 Nebular 页面；随后按需选用 主题组件 目录下的各类 UI 组件（按钮、卡片、表单、表格、对话框等），组件示例可直接参考 playground 示例代码。

注意事项与常见问题

• ngx-admin 自定义组件：本指南只解决 Nebular 模块的安装；ngx-admin 的自定义组件（如温度小部件、仪表盘图表）需要按本文完成接入后手动拷贝并注册到你的模块中；
• 动画模块冲突：若工程已显式使用NoopAnimationsModule，ng add不会自动覆盖，而会提示手动配置BrowserAnimationsModule；
• 主题重复引入：ng add与手动配置都会校验angular.json中是否已存在其他@nebular/theme/styles/prebuilt样式，避免同一主题被重复引入；
• 版本兼容：手动安装时务必保证@angular/cdk、@angular/animations等 peer 依赖版本与@nebular/theme当前版本声明一致，具体以仓库中 package.json 为准。

• 前端
• UI组件