TypeScript定义JsonWebToken字符串类型遇TS2322错误求助

错误原因 #

你定义的EncodedString<T>是继承自内置String对象的接口，属于对象类型，而TypeScript的模板字面量类型（${X}）仅允许原始类型（string、number、bigint、boolean等）作为插值项。Base64UrlString作为对象类型无法被模板字面量接受，因此触发TS2322类型不匹配错误。

另外需要注意：你定义的Base64UrlCharacter不符合实际Base64Url标准——Base64Url会用-替代+、_替代/，这一点需要修正。

解决方案 #

方案1：品牌类型标记（简单实用） #

去掉继承String的自定义接口，用品牌类型标记符合Base64Url格式的字符串，既保留原始string类型的特性（可用于模板字面量），又能在类型层面区分普通字符串：

// 修正后的Base64Url字符集，符合标准
type Base64UrlCharacter =
  'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' |
  'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' |
  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '-' | '_';

// 品牌类型：标记这是Base64Url格式的字符串
type Base64UrlString = string & { __brand: 'Base64Url' };
type JsonWebTokenMessage = `${Base64UrlString}.${Base64UrlString}`;
type JsonWebTokenString = `${JsonWebTokenMessage}.${Base64UrlString}`;

方案2：递归类型约束（编译时校验字符） #

如果需要在编译时强制校验字符串仅由允许的字符组成，可以使用TypeScript 4.8+支持的递归条件类型：

type Base64UrlCharacter =
  'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' |
  'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' |
  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '-' | '_';

// 递归约束字符串仅由Base64UrlCharacter组成
type Base64UrlString<T extends string = string> = 
  T extends `${Base64UrlCharacter}${infer Rest}` 
    ? Rest extends '' ? T : Base64UrlString<Rest>
    : never;

type JsonWebTokenMessage = `${Base64UrlString}.${Base64UrlString}`;
type JsonWebTokenString = `${JsonWebTokenMessage}.${Base64UrlString}`;

注意：递归类型有深度限制，过长的字符串可能触发TypeScript递归深度报错，适合短字符串场景。

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