Angular 18使用NgOptimizedImage报错NG8002：无法绑定'ngSrc'

问题描述 #

在Angular 18项目中使用NgOptimizedImage指令时，图片无法正常显示，触发错误：

NG8002: Can't bind to 'ngSrc' since it isn't a known property of 'img'

已在父模块中导入NgOptimizedImage，相关代码如下：

HTML模板 #

<div class="awards-content">
        <div class="awards-screen">
            <div  class="align-awards text-primary">
                <h4 class="label-title">Awards...</h4>
            </div>
            <div>
                <p>
                <span class="text-primary">
                    <a class="spacer"
                      href="https://github.com/lkovari/LKovariHome/blob/master/src/app/layout-pages/awards/awards.component.ts">
                      <img [src]="githubLogoPath" width="16" height="16" alt="githubLogoPath">
                    </a>Technical notes:</span> under CONSTRUCTION, will use ngOptimizedImage directive</p>
            </div>
            <div class="image-content">
                <ul>
                    @for (imageDescriptor of imageDescriptors; track imageDescriptor.id) {
                        <li class="text-primary">  {{ imageDescriptor.alt }}
                            <img
                                class="img-responsive"
                                [ngSrc]="imageDescriptor.fileName" 
                                [width]="imageDescriptor.width"
                                [height]="imageDescriptor.height"
                                [alt]="imageDescriptor.alt"
                                ngSrcset="200w, 400w, 600w, 800w, 1000w, 1200w, 1600w, 2000w, 3000w">
                        </li>            
                    }
                </ul>
            </div>            
        </div>
</div>

组件TS代码 #

import { Component, OnInit } from '@angular/core';
import { ImageDescriptor } from './models/image-descriptor.interface';

@Component({
  selector: 'app-awards',
  templateUrl: './awards.component.html',
  styleUrls: ['./awards.component.scss']
})
export class AwardsComponent implements OnInit {
  githubLogoPath: string;
  public years: number;
  imageDescriptors: ImageDescriptor[] = [
    { id : 1, fileName: 'assets/images/2022Q2LeaderboardWinnerGT50.png', width: 434, height: 640, alt: 'Leaderboard winner Q2 of 2022' },
    { id : 2, fileName: 'assets/images/2021Q4CaughtAtYourBest.png', width: 791, height: 916, alt: 'Caught at your best Q4 2021' },
    { id : 3, fileName: 'assets/images/2018CertificateOfRecognition20years.png', width: 800, height: 583, alt: '20 years of service' },
    { id : 4, fileName: 'assets/images/2016Q4CaughtAtYourBest.png', width: 1280, height: 983, alt: 'Caught at your best Q4 2016' },
    { id : 5, fileName: 'assets/images/2015Q4CaughtAtYourBest.png', width: 1280, height: 913, alt: 'Caught at your best Q4 2015' },
    { id : 6, fileName: 'assets/images/icagile-cert2014.png', width: 800, height: 583, alt: 'IcAgile course Certificate' },
    { id : 7, fileName: 'assets/images/AmkaiStockOptions1050A.png', width: 1199, height: 913, alt: 'Stock Option Series A' }
  ]

  constructor() { }

  ngOnInit() {
    const date = new Date();
    this.years = date.getFullYear();
    this.githubLogoPath = 'assets/logos/GitHub-Mark-32px.png';
  }

}

解决方案 #

1. 确认NgOptimizedImage的导入位置 #

确保NgOptimizedImage正确添加到组件所在模块的imports数组中（而非declarations）：

// 组件所在的父模块（比如AwardsModule或AppModule）
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NgOptimizedImage } from '@angular/common'; // 导入指令
import { AwardsComponent } from './awards/awards.component';

@NgModule({
  imports: [
    BrowserModule,
    NgOptimizedImage // 必须加到imports里
  ],
  declarations: [AwardsComponent],
  exports: [AwardsComponent]
})
export class AwardsModule { }

2. 独立组件场景的处理（如果使用） #

若你的组件启用了standalone: true（当前代码未启用，仅作补充），需在组件自身的imports数组中导入NgOptimizedImage：

@Component({
  selector: 'app-awards',
  templateUrl: './awards.component.html',
  styleUrls: ['./awards.component.scss'],
  standalone: true,
  imports: [NgOptimizedImage] // 独立组件需在此导入
})
export class AwardsComponent implements OnInit {
  // ...组件逻辑
}

3. 清除缓存并重启开发服务 #

Angular CLI的缓存可能导致指令未被正确识别，执行以下命令清理缓存后重启服务：

ng serve --clear-cache

或手动删除依赖文件后重新安装：

rm -rf node_modules package-lock.json
npm install

4. 验证Angular包版本兼容性 #

确保@angular/common包版本与Angular 18匹配，执行更新命令：

npm install @angular/common@18

5. 修正ngSrcset语法（可选优化） #

NgOptimizedImage的ngSrcset支持自动生成不同尺寸的图片链接，若手动指定需确保格式正确。如果没有对应尺寸的图片资源，可移除该属性让指令自动处理，或调整为数组绑定格式：

<img
  class="img-responsive"
  [ngSrc]="imageDescriptor.fileName" 
  [width]="imageDescriptor.width"
  [height]="imageDescriptor.height"
  [alt]="imageDescriptor.alt"
  [ngSrcset]="['200w', '400w', '600w']"> <!-- 数组绑定更规范 -->

内容的提问来源于stack exchange，提问作者L. Kvri