Angular 17预渲染：构建时调用CMS API获取动态内容问询

问题背景 #

Angular 17已原生支持预渲染，但官方文档未明确说明如何通过外部CMS的REST API驱动动态路由预渲染。目前已用模拟数据完成首页和article/:id路由的预渲染，但构建阶段无法获取CMS接口内容，仅运行时可正常调用；首页已链接/article/1、/article/2、/article/3三个文章路由。

当前代码参考 #

路由配置

export const routes: Routes = [
    {
        path: '',
        component: HomeComponent,
        title: 'Home page'
      },
      {
        path: 'article/:id',
        component: ArticleDetailsComponent,
        title: 'Article Details'
      }
];

article.service.ts

@Injectable({
  providedIn: 'root'
})
export class ArticleService {
  constructor(private http: HttpClient) { }

  articleList: Article[] = [
    {
      id: 1,
      title: 'my article time',
      subTitle: 'sub title'
    }
    // 其他模拟文章数据
  ]

  getArticleById(id: number): Article | undefined {
    let article = this.articleList.find(article => article.id === id);

    // 后续计划由Go服务处理转换逻辑
    if (article !== undefined) {
      article = this.transformContent(article);
    }

    return article;
  }


  getArticleFromCMS(): Observable<Content> {
    return this.http.get<Content>('https://example.com')
      .pipe(
        catchError(this.handleError<Content>('getArticle', {}))
      );
  }
}

article-details.component.ts

import { Component, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ActivatedRoute } from '@angular/router';
import { ArticleService } from '../article.service';
import { Article, CMSContent } from '../article';

@Component({
  selector: 'app-article-details',
  standalone: true,
  imports: [CommonModule],
  templateUrl: './article-details.component.html',
  styleUrl: './article-details.component.css'
})
export class ArticleDetailsComponent {
  route: ActivatedRoute = inject(ActivatedRoute);
  articleService = inject(ArticleService);
  article: Article | undefined;
  cmsContent: CMSContent | undefined;

  constructor() {
    const articleID = Number(this.route.snapshot.params['id']);
    this.article = this.articleService.getArticleById(articleID);
  }

  ngOnInit(): void {
    this.getArticles();
  }

  getArticles(): void {
    this.articleService.getArticleFromCMS()
      .subscribe(article => this.cmsContent = article.content[0]);
  }
}

解决方案 #

1. 动态生成预渲染路由列表 #

预渲染需要明确知道要渲染哪些路由，需在构建阶段从CMS获取所有需要预渲染的文章ID，生成完整路由列表。修改server.ts添加路由生成逻辑：

import { APP_BASE_HREF } from '@angular/common';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter, withPreloading, PreloadAllModules } from '@angular/router';
import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
import { provideHttpClient, HttpClient, HttpXhrBackend } from '@angular/common/http';

// 从CMS获取所有文章ID
async function fetchArticleIds(): Promise<number[]> {
  const http = new HttpClient(new HttpXhrBackend({ build: () => new XMLHttpRequest() }));
  try {
    // 替换为实际CMS获取文章列表的接口
    const res = await http.get<{ content: { id: number }[] }>('https://example.com/articles').toPromise();
    return res.content.map(item => item.id);
  } catch (err) {
    console.error('获取文章ID失败，使用默认列表:', err);
    return [1, 2, 3]; // 失败时回退到已知ID
  }
}

// 生成需预渲染的路由
async function getPrerenderRoutes() {
  const ids = await fetchArticleIds();
  return [
    '/',
    ...ids.map(id => `/article/${id}`)
  ];
}

bootstrapApplication(AppComponent, {
  providers: [
    provideRouter(routes, withPreloading(PreloadAllModules)),
    provideHttpClient(),
    { provide: APP_BASE_HREF, useValue: '/' },
  ]
}).then(async appRef => {
  // 仅在服务器/预渲染环境执行
  if (typeof window === 'undefined') {
    const prerenderRoutes = await getPrerenderRoutes();
    // 将路由列表传递给预渲染工具（Angular CLI会自动识别此逻辑）
    (globalThis as any).prerenderRoutes = prerenderRoutes;
  }
});

2. 用路由Resolve守卫预取CMS内容 #

预渲染过程是同步的，不能依赖组件内的异步订阅，需通过路由resolve守卫在路由激活前获取数据，确保预渲染时内容已准备好。

创建ArticleResolve守卫

import { Injectable } from '@angular/core';
import { Resolve, ActivatedRouteSnapshot } from '@angular/router';
import { Observable, of } from 'rxjs';
import { ArticleService } from './article.service';
import { CMSContent } from './article';

@Injectable({ providedIn: 'root' })
export class ArticleResolve implements Resolve<CMSContent | undefined> {
  constructor(private articleService: ArticleService) {}

  resolve(route: ActivatedRouteSnapshot): Observable<CMSContent | undefined> {
    const articleId = route.paramMap.get('id');
    if (articleId) {
      // 替换为CMS按ID查询的接口
      return this.articleService.getArticleFromCMSById(Number(articleId));
    }
    return of(undefined);
  }
}

更新ArticleService，添加按ID获取CMS内容的方法

// 在article.service.ts中新增
getArticleFromCMSById(id: number): Observable<CMSContent> {
  return this.http.get<CMSContent>(`https://example.com/articles/${id}`)
    .pipe(catchError(this.handleError<CMSContent>('getArticleById', {})));
}

修改路由配置，关联Resolve守卫

export const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home page'
  },
  {
    path: 'article/:id',
    component: ArticleDetailsComponent,
    title: 'Article Details',
    resolve: {
      cmsContent: ArticleResolve
    }
  }
];

调整组件，直接读取预取的内容

移除组件内的异步请求逻辑，从路由快照中获取预渲染好的CMS内容：

export class ArticleDetailsComponent {
  route: ActivatedRoute = inject(ActivatedRoute);
  articleService = inject(ArticleService);
  article: Article | undefined;
  cmsContent: CMSContent | undefined;

  constructor() {
    const articleID = Number(this.route.snapshot.params['id']);
    this.article = this.articleService.getArticleById(articleID);
    // 直接从路由resolve数据中获取CMS内容
    this.cmsContent = this.route.snapshot.data['cmsContent'];
  }

  // 移除原ngOnInit和getArticles方法，预渲染时已完成数据获取
}

3. 配置Angular CLI预渲染参数 #

修改angular.json中的prerender配置，允许动态生成路由：

{
  "projects": {
    "your-project-name": {
      "architect": {
        "prerender": {
          "builder": "@angular-devkit/build-angular:prerender",
          "options": {
            "routes": [], // 留空，使用server.ts中生成的动态路由
            "serverTarget": "your-project-name:server"
          }
        }
      }
    }
  }
}

关键注意事项 #

• 确保CMS接口在构建服务器环境中可访问，避免跨域或内网权限限制。
• 若CMS接口需要认证，需在fetchArticleIds和getArticleFromCMSById方法中添加认证头（如API密钥）。
• 文章数量较多时，可分页获取ID，避免单次请求数据量过大导致超时。

内容的提问来源于stack exchange，提问作者Jeff Sloyer