常见编译错误与解决方案

TypeScript 作为 JavaScript 的超集，在编译时提供了类型检查能力，但开发者常会遇到各种编译错误。以下是几种典型错误及其解决方案。

类型不匹配错误

类型不匹配是 TypeScript 中最常见的错误之一。当变量或函数的实际类型与声明的类型不一致时，编译器会抛出错误。

let age: number = "25"; // Error: Type 'string' is not assignable to type 'number'

解决方案是确保类型一致：

let age: number = 25; // 正确

对于函数参数类型不匹配的情况：

function greet(name: string) {
  console.log(`Hello, ${name}`);
}
greet(123); // Error: Argument of type 'number' is not assignable to parameter of type 'string'

修正方法：

greet("Alice"); // 正确

未定义变量错误

当使用未声明的变量时，TypeScript 会报错。

console.log(undeclaredVar); // Error: Cannot find name 'undeclaredVar'

解决方案是声明变量：

let undeclaredVar = "value";
console.log(undeclaredVar); // 正确

可选参数与默认参数混淆

开发者有时会混淆可选参数和默认参数的语法。

function createUser(name: string, age?: number = 18) { // Error: Parameter cannot have question mark and initializer
  // ...
}

正确写法：

// 可选参数
function createUser(name: string, age?: number) {
  age = age || 18;
}

// 或使用默认参数
function createUser(name: string, age: number = 18) {
  // ...
}

模块导入导出错误

当导入/导出模块时，路径或名称错误会导致编译失败。

import { helper } from './utils'; // Error: Module not found if file doesn't exist

确保文件路径正确：

import { helper } from './utils.ts'; // 正确（假设文件存在）

对于默认导出和命名导出的混淆：

// utils.ts
export default function helper() {}

// main.ts
import { helper } from './utils'; // Error: Module has no exported member 'helper'

应改为：

import helper from './utils'; // 正确

类型断言错误

不恰当的类型断言会导致运行时错误。

let value: any = "hello";
let length: number = (<string>value).length; // 正确但不安全

value = 123;
length = (<string>value).length; // 编译通过但运行时错误

更安全的做法是使用类型守卫：

if (typeof value === 'string') {
  length = value.length; // 安全
}

泛型约束问题

当泛型参数不满足约束条件时会报错。

function getLength<T>(arg: T): number {
  return arg.length; // Error: Property 'length' does not exist on type 'T'
}

添加泛型约束：

interface Lengthwise {
  length: number;
}

function getLength<T extends Lengthwise>(arg: T): number {
  return arg.length; // 正确
}

装饰器应用错误

装饰器语法错误或应用位置不当会导致编译失败。

@sealed // Error: Decorators are not valid here
class Greeter {
  greeting: string;
}

确保装饰器应用在支持的位置：

function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@sealed // 正确
class Greeter {
  greeting: string;
}

枚举类型冲突

枚举成员命名冲突或值重复会导致问题。

enum Color {
  Red = 1,
  Green = 1, // 允许但不推荐
  Blue // 2
}

let color: Color = Color.Red; // 可能不是预期行为

最佳实践是为每个枚举成员分配唯一值：

enum Color {
  Red = 1,
  Green = 2,
  Blue = 3
}

接口实现不完整

类实现接口时遗漏成员会报错。

interface Person {
  name: string;
  age: number;
}

class Student implements Person { // Error: Property 'age' is missing
  name: string;
}

完整实现接口：

class Student implements Person {
  name: string;
  age: number;
}

只读属性修改尝试

尝试修改只读属性会导致编译错误。

interface Point {
  readonly x: number;
  y: number;
}

let p: Point = { x: 10, y: 20 };
p.x = 5; // Error: Cannot assign to 'x' because it is a read-only property

解决方案是避免修改只读属性：

p.y = 15; // 允许修改非只读属性

函数重载实现不匹配

函数重载声明与实际实现不一致会报错。

function padding(all: number): string;
function padding(topAndBottom: number, leftAndRight: number): string;
function padding(top: number, right: number, bottom: number, left: number): string;
function padding(a: number, b?: number, c?: number, d?: number) { // 实现必须兼容所有重载
  // ...
}

如果实现不兼容：

function padding(a: string, b?: number) { // Error: This overload signature is not compatible
  // ...
}

类型别名循环引用

类型别名之间的循环引用会导致错误。

type A = B; // Error: Type alias 'A' circularly references itself
type B = A;

打破循环引用：

type A = {
  b: B;
}
type B = {
  a?: A;
}

索引签名冲突

当接口已明确定义属性时，索引签名会冲突。

interface Dictionary {
  [key: string]: string;
  name: string;
  age: number; // Error: Property 'age' of type 'number' is not assignable to string index type 'string'
}

解决方案是使索引签名更宽松：

interface Dictionary {
  [key: string]: string | number;
  name: string;
  age: number; // 现在正确
}

严格空值检查问题

启用 strictNullChecks 时，潜在的空值访问会报错。

let element: HTMLElement | null = document.getElementById('app');
element.innerHTML = 'hello'; // Error: Object is possibly 'null'

添加空值检查：

if (element !== null) {
  element.innerHTML = 'hello';
}

或使用非空断言（谨慎使用）：

element!.innerHTML = 'hello';

类型扩展不足

尝试访问对象上不存在的属性会报错。

interface BasicUser {
  name: string;
}

let user: BasicUser = { name: 'Alice' };
console.log(user.age); // Error: Property 'age' does not exist on type 'BasicUser'

解决方案是扩展接口：

interface FullUser extends BasicUser {
  age?: number;
}

let user: FullUser = { name: 'Alice' };
console.log(user.age); // 正确，age是可选属性

异步函数类型错误

忘记处理 Promise 返回值会导致类型问题。

async function fetchData(): Promise<string> {
  return "data";
}

let result = fetchData(); // result 是 Promise<string> 不是 string
console.log(result.length); // Error: Property 'length' does not exist on type 'Promise<string>'

正确处理 Promise：

fetchData().then(data => {
  console.log(data.length); // 正确
});

或在 async 函数中使用 await：

async function process() {
  let data = await fetchData();
  console.log(data.length); // 正确
}

类型推断意外结果

有时类型推断结果不符合预期。

let x = null; // x 被推断为 any
x = 123; // 允许但不安全

启用严格模式后：

let y: string | null = null;
y = "text"; // 正确
y = 123; // Error: Type 'number' is not assignable to type 'string | null'

联合类型操作限制

直接操作联合类型变量会报错。

function padLeft(value: string, padding: string | number) {
  return Array(padding + 1).join(" ") + value; // Error: Operator '+' cannot be applied to types 'string | number' and 'number'
}

使用类型检查：

function padLeft(value: string, padding: string | number) {
  if (typeof padding === "number") {
    return Array(padding + 1).join(" ") + value;
  }
  return padding + value;
}

类静态成员访问错误

混淆实例成员和静态成员会导致错误。

class MyClass {
  static staticMethod() {}
  instanceMethod() {}
}

let instance = new MyClass();
instance.staticMethod(); // Error: Property 'staticMethod' does not exist on type 'MyClass'

正确访问方式：

MyClass.staticMethod(); // 正确
instance.instanceMethod(); // 正确

类型保护失效

不正确的类型保护会导致编译错误。

function isString(test: any): boolean {
  return typeof test === "string";
}

function example(foo: any) {
  if (isString(foo)) {
    console.log(foo.length); // Error: Property 'length' does not exist on type 'any'
  }
}

使用正确的类型谓词：

function isString(test: any): test is string {
  return typeof test === "string";
}

function example(foo: any) {
  if (isString(foo)) {
    console.log(foo.length); // 正确
  }
}

映射类型修改只读属性

尝试通过映射类型修改只读属性会报错。

type ReadonlyPerson = {
  readonly name: string;
  readonly age: number;
}

type Mutable<T> = {
  -readonly [P in keyof T]: T[P];
}

let person: Mutable<ReadonlyPerson> = { name: "Alice", age: 30 };
person.name = "Bob"; // 正确，去除了 readonly

条件类型使用不当

复杂的条件类型可能导致意外错误。

type TypeName<T> =
  T extends string ? "string" :
  T extends number ? "number" :
  "other";

let a: TypeName<string> = "string"; // 正确
let b: TypeName<boolean> = "other"; // 正确
let c: TypeName<string> = "number"; // Error: Type '"number"' is not assignable to type '"string"'

声明文件冲突

重复的声明会导致冲突。

declare module "my-module" {
  export function foo(): string;
}

declare module "my-module" {
  export function bar(): number; // 合并声明
}

// 但以下会导致冲突
interface MyInterface {
  prop: string;
}

interface MyInterface {
  prop: number; // Error: Subsequent property declarations must have the same type
}

类型兼容性误判

结构类型系统可能导致意外兼容。

interface Named {
  name: string;
}

class Person {
  name: string = "";
}

let p: Named;
p = new Person(); // 正确，因为结构兼容

但以下情况不兼容：

interface Named {
  name: string;
  age?: number;
}

class Person {
  name: string = "";
  age: number = 0;
}

let p: Named = new Person(); // 仍然正确
let p2: Person = { name: "Alice" }; // Error: Property 'age' is missing

函数参数解构类型错误

解构参数时类型标注位置错误。

function draw({ shape: Shape, xPos: number }) { // Error: 'number' is a type but used as value
  // ...
}

正确写法：

function draw({ shape, xPos }: { shape: Shape, xPos: number }) {
  // ...
}

类型查询错误

对变量使用 typeof 作为类型时可能出错。

let size = 10;
let arr: Array<typeof size>; // Error: 'size' refers to a value but is being used as a type

// 正确用法
type Size = typeof size; // 先定义类型
let arr: Array<Size>; // 正确

类表达式类型问题

类表达式中的类型可能不符合预期。

const MyClass = class<T> {
  content: T;
  constructor(value: T) {
    this.content = value;
  }
};

let instance = new MyClass("hello");
instance.content = 123; // Error: Type 'number' is not assignable to type 'string'

显式指定类型参数：

let instance = new MyClass<string>("hello");
instance.content = "world"; // 正确

命名空间合并问题

合并命名空间时可能产生冲突。

namespace N {
  export let x = 1;
}

namespace N {
  export let x = 2; // Error: Duplicate identifier 'x'
}

正确合并方式：

namespace N {
  export let x = 1;
}

namespace N {
  export let y = x; // 可以访问之前导出的x
}

类型参数默认值错误

泛型类型参数默认值使用不当。

function createArray<T = string>(length: number, value: T): Array<T> {
  return Array(length).fill(value);
}

let arr = createArray(3, 123); // T 被推断为 number
let arr2 = createArray(3); // Error: Expected 2 arguments but got 1

索引访问类型错误

通过索引访问类型时可能出错。

type Person = { name: string; age: number };
type Age = Person["age"]; // number
type NonExist = Person["address"]; // Error: Property 'address' does not exist

模板字面量类型错误

模板字面量类型使用不当。

type Color = "red" | "blue";
type Quantity = "one" | "two";

type Sentence = `${Quantity} ${Color} apples`; // "one red apples" | "one blue apples" | "two red apples" | "two blue apples"

let s: Sentence = "three red apples"; // Error: Type '"three red apples"' is not assignable to type 'Sentence'

类型谓词作用域

类型谓词的作用域有限。

function isNumber(x: any): x is number {
  return typeof x === "number";
}

let x: string | number = Math.random() > 0.5 ? "hello" : 123;

if (isNumber(x)) {
  x.toFixed(2); // 正确
}
x.toFixed(2); // Error: 'toFixed' does not exist on type 'string'

构造函数类型错误

混淆构造函数类型和实例类型。

class Animal {
  constructor(public name: string) {}
}

type AnimalConstructor = typeof Animal;
type AnimalInstance = InstanceType<AnimalConstructor>;

let create = (ctor: AnimalConstructor, name: string): AnimalInstance => {
  return new ctor(name);
};

let animal = create(Animal, "Fido"); // 正确

类型扩展污染

全局类型扩展可能导致意外行为。

// 不推荐的全局扩展
declare global {
  interface Array<T> {
    shuffle(): void;
  }
}

Array.prototype.shuffle = function() {
  // 实现
};

// 可能与其他库的扩展冲突

类型导入混淆

混淆类型导入和值导入。

// utils.ts
export function helper() {}
export type HelperOptions = { /* ... */ };

// main.ts
import { helper, HelperOptions } from './utils';

let options: HelperOptions = {}; // 正确
helper(); // 正确

// 错误示例
let HelperOptions = 123; // Error: Duplicate identifier 'HelperOptions'

类型兼容性检查绕过

使用 any 绕过类型检查可能导致问题。

function unsafeCast<T>(value: any): T {
  return value;
}

let str: string = unsafeCast(123); // 编译通过但运行时风险

更安全的替代方案：

function safeCast<T>(value: unknown): T | never {
  if (typeof value === "string") {
    return value as T;
  }
  throw new Error("Invalid cast");
}

类型递归深度限制

过深的递归类型可能导致错误。

type Json =
  | string
  | number
  | boolean
  | null
  | { [property: string]: Json }
  | Json[];

// 深层嵌套可能导致性能问题或错误
let deepJson: Json = {
  level1: {
    level2: {
      /* ... */
    }
  }
};

类型参数约束不满足

泛型参数不满足约束条件。

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

longest(10, 20); // Error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'

传递符合约束的参数：

longest("Alice", "Bob"); // 正确
longest([1, 2], [3]); // 正确

类型别名与接口选择

不恰当地选择类型别名或接口。

// 适合使用接口的场景
interface Point {
  x: number;
  y: number;
}

// 适合使用类型别名的场景
type PointTuple = [number, number];

类型推断与上下文类型

上下文类型可能导致意外推断结果。

window.onmousedown = function(mouseEvent) {
  console.log(mouseEvent.button); //