Angular SSR localStorage未定义错误解决方案

TypeScript调用localStorage

在Angular应用开发中，使用TypeScript调用localStorage是常见的操作。通常情况下，通过key从localStorage中取出数据，一行代码即可完成。

然而，当应用运行在服务器端渲染（SSR）模式下，这段代码会直接崩溃，并抛出一个令人头疼的错误：
“ReferenceError: localStorage is undefined”。

原因很简单：服务器上没有浏览器端的全局API。例如，无法像在客户端环境中那样，直接通过全局变量访问document对象。要获取document的引用，需要借助Angular的DOCUMENT令牌和依赖注入（DI）机制来迂回实现。

因此，核心思路很明确：避免在全局空间中直接调用浏览器API，改为通过依赖注入对应的服务。这样在服务器端渲染时，可以替换为安全的实现或直接禁用，确保应用不会出错。

先看一个基础示例：

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实现。

错误分析

如何解决？方法很简单：在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），这样组件只负责自己的业务逻辑，模板也更加清晰。

创建Injection Token

首先定义一个专用的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 {}

额外的属性已被完全移除，模板只关注展示什么内容，这正是结构型指令应有的设计。