Angular application 运行后显示空白页面

2026-11-04排障赵师傅

结论

ng serve 编译成功只能确认代码通过了构建。应用仍可能在浏览器运行 Angular 时出现异常，使根组件无法完成渲染，最终显示为空白页面，并在 Console 中报错。

目前没有具体的 Console 错误和版本信息，暂时无法确定原因。先处理 Console 中的第一条错误，再检查路由、根组件和接口配置，因为后续报错很可能由第一条错误连带产生。

先确认运行时错误

打开 Chrome 开发者工具并切换到 Console，刷新页面，找到第一条红色错误，展开查看调用栈。常见错误及排查方向如下：

Console 错误	常见原因
`NullInjectorError: No provider for ...`	服务或依赖没有注册
`Cannot match any routes`	路由地址或重定向配置错误
`ChunkLoadError`	懒加载文件未加载、缓存过期或部署路径错误
`Failed to fetch dynamically imported module`	懒加载模块路径或静态资源地址错误
`Cannot read properties of undefined`	初始化代码使用了尚未赋值的数据
`NG...` 开头的错误	Angular 模板、依赖注入或启动过程异常
`404`、`401`、`CORS`	接口地址、认证服务或跨域配置有问题

同时打开 Network 面板。刷新页面后，检查 main.js、styles.css、懒加载 chunk 和配置文件是否返回 404 或 500。

检查 Angular 是否成功启动

传统 NgModule 项目的 main.ts 通常采用以下写法：

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch(err => console.error(err));

Standalone 项目通常使用：

bootstrapApplication(AppComponent, appConfig)
  .catch(err => console.error(err));

保留 .catch(...)，这样启动失败的具体原因才能输出到 Console。

接着核对 index.html 中的根元素和根组件的 selector：

<!-- src/index.html -->
<app-root></app-root>

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {}

两处名称必须一致，否则 Angular 无法将应用挂载到页面。

检查登录页路由

如果访问 / 时应当显示登录页，需要配置默认路由或重定向。

NgModule 路由示例：

const routes: Routes = [
  {
    path: '',
    pathMatch: 'full',
    redirectTo: 'login'
  },
  {
    path: 'login',
    component: LoginComponent
  },
  {
    path: '**',
    redirectTo: 'login'
  }
];

Standalone 项目的路由写法相同：

export const routes: Routes = [
  { path: '', pathMatch: 'full', redirectTo: 'login' },
  { path: 'login', component: LoginComponent }
];

根组件模板中必须有路由出口：

<router-outlet></router-outlet>

NgModule 项目还要导入路由配置：

@NgModule({
  imports: [
    BrowserModule,
    AppRoutingModule
  ]
})
export class AppModule {}

Standalone 项目需要注册 Router：

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes)
  ]
};

可以直接访问 http://localhost:4200/login。如果该地址可以正常显示，而 / 仍是空白页面，通常需要检查默认路由或重定向配置。

检查认证守卫和接口配置

团队项目常在启动阶段加载用户信息、远程配置或认证状态。如果相关服务在本地不可用，路由守卫可能一直等待，也可能将用户重定向到错误地址。

需要检查：

environment.ts 中的 API 地址是否适用于本地环境。
Network 面板中的登录、配置和用户信息请求是否失败。
CanActivate、CanMatch 或初始化服务是否始终返回结果。
本地是否缺少团队内部使用的环境变量、代理或后端服务。
是否存在循环重定向，例如 / 跳转到 /login，登录守卫又将 /login 跳回 /。

路由守卫应返回明确结果。例如：

canActivate(): Observable<boolean | UrlTree> {
  return this.authService.getCurrentUser().pipe(
    map(user => user ? true : this.router.createUrlTree(['/login'])),
    catchError(() =>
      of(this.router.createUrlTree(['/login']))
    )
  );
}

如果 Observable 一直不发出值，导航就会持续等待，页面看起来也可能是一片空白。

核对依赖和版本

团队项目应使用代码库中记录的版本，先执行：

node --version
npm --version
npx ng version

然后核对 package.json 中的 @angular/core、@angular/cli 和 typescript 版本，并查看项目是否提供 .nvmrc 或 engines 配置。

如果仓库中有 package-lock.json，可以执行：

npm ci
npx ng serve

npm ci 会按照锁文件安装依赖，适合还原团队项目的依赖环境。在确认原因之前，不要升级 Angular、TypeScript，也不要删除锁文件，以免版本变化带来新的兼容问题。

仍然空白时的最小化检查

可以临时将根组件模板改成简单文本：

<h1>Angular started</h1>
<router-outlet></router-outlet>

如果这段文字也没有显示，应检查应用启动、根组件挂载和静态资源加载。如果文字能够显示，但登录页没有出现，则继续排查路由、登录组件、守卫和接口请求。

继续定位问题时，请保留 Console 中第一条错误的完整内容和调用栈、Network 中的失败请求，以及 npx ng version 的输出。缺少这些信息时，只能缩小排查范围，无法确定具体需要修改哪一行代码。