Angular服务端渲染localStorage未定义错误全面分析与解决方法

TypeScript 调用 localStorage 的完整指南与 SSR 解决方案

在 Angular 应用开发中，使用 TypeScript 调用 localStorage 是一项非常常见的操作。通常只需通过 key 从 local storage 中取出数据，一行代码即可完成。但在服务端渲染（SSR）模式下，这段代码会直接崩溃，抛出令人头疼的错误：
“ReferenceError: localStorage is undefined”。

错误根源在于：服务器环境中不存在浏览器内置的全局 API。例如，你不能像在客户端那样直接通过全局变量访问 document 对象。要获取 document 的引用，必须借助 Angular 的 DOCUMENT 令牌和依赖注入（DI）机制来间接实现。

核心解决思路很明确：放弃使用全局空间直接调用浏览器 API，改为通过 DI 注入对应的服务。这样在服务端渲染时，要么替换为一个安全的实现，要么直接禁用该功能，确保应用不会崩溃。

先看一个基础示例：

import {Component, Inject, NgModule} from '@angular/core';
import {LOCAL_STORAGE} from '@ng-web-apis/common';
@Component({...})
export class SomeComponent {
  constructor(@Inject(LOCAL_STORAGE) localStorage: Storage) {
    localStorage.getItem('key');
  }
}

这里用到了 @ng-web-apis/common 包提供的 LOCAL_STORAGE 令牌。但仅凭这段代码，在服务器上运行仍然会报错——因为服务端没有真正的 localStorage 实现。

错误分析与 SSR 兼容方案

如何彻底解决？方法很简单：在 AppServerModule 的 providers 中添加一个来自 @ng-web-apis/universal 包的 UNIVERSAL_LOCAL_STORAGE，并将其与 LOCAL_STORAGE 令牌绑定。这样一来，服务端就能拥有一个安全的“localStorage”实现，不会再报 undefined 错误。

import { NgModule } from '@angular/core';
import {
    ServerModule,
} from '@angular/platform-server';
import { AppModule } from './app.module';
import { AppComponent } from './app.component';
import { UNIVERSAL_LOCAL_STORAGE } from '@ng-web-apis/universal';
@NgModule({
  imports: [
    AppModule,
    ServerModule,
  ],
  providers: [UNIVERSAL_LOCAL_STORAGE],
  bootstrap: [AppComponent],
})
export class AppServerModule {}

再看一个更常见的场景：条件渲染。你可能会这样写——在组件中判断当前是否为服务端平台，将结果暴露到模板中，配合 ngIf 控制显示：

<>
@Component({
  selector: 'ram-root',
  template: '',
  styleUrls: ['./app.component.less'],
})
export class AppComponent {
  isServer = isPlatformServer(this.platformId);
  constructor(@Inject(PLATFORM_ID) private platformId: Object){}
}

这段代码本身没什么大问题，但组件中多了一个与业务无关的属性 isServer，模板也因此显得不够整洁。有没有更优雅的实现方式？

优雅实现：提取平台判断逻辑

思路是将平台判断逻辑封装成一个独立的结构型指令（structural directive），这样组件只需关心自身业务，模板也更加干净。

创建 InjectionToken

首先定义一个专用的 InjectionToken，其工厂函数直接调用 isPlatformServer 并将结果缓存：

<>
export const IS_SERVER_PLATFORM = new InjectionToken('Is server?', {
  factory() {
    return isPlatformServer(inject(PLATFORM_ID));
  },
});

创建自定义指令

接着编写一个结构型指令 IfIsServerDirective，注入这个 token 的值，如果是服务端则动态创建视图：

@Directive({
  selector: '[ifIsServer]',
})
export class IfIsServerDirective {
  constructor(
    @Inject(IS_SERVER_PLATFORM) isServer: boolean,
    templateRef: TemplateRef,
    viewContainer: ViewContainerRef
  ) {
    if (isServer) {
      viewContainer.createEmbeddedView(templateRef);
    }
  }
}

最后，在组件模板中直接使用这个指令即可——简洁、清晰，业务组件不再包含任何平台相关的代码：

<>
@Component({
  selector: 'ram-root',
  template: '',
  styleUrls: ['./app.component.less'],
})
export class AppComponent {}

多余的属性已全部移除，模板只关注展示什么内容，这才是结构型指令应有的设计理念。