为何Lit的css模板字面量函数无法正常插值变量？

问题描述 #

我尝试按如下方式抽象Web组件主题：

import { css } from 'lit';

const theme = {
  primary: '#fff'
}

export const baseCss = css`
  :host {
    --primary: ${theme.primary}
  }
`

但在TypeScript中无法运行，报错信息为：

Argument of type 'string' is not assignable to parameter of type 'number | CSSResultGroup'.

想知道为什么Lit提供的模板字面量函数无法接收变量插值？是否是因为代码注入问题？因为unsafeCSS可以正常工作。

核心原因：Lit的css模板字面量安全设计 #

Lit的css模板函数不允许直接插入普通字符串，本质是为了防止CSS注入攻击，同时保障样式的可预测性与性能优化。

1. 类型校验与安全机制 #

css函数要求插值内容必须是CSSResultGroup类型（包括CSSResult、number或这些类型的数组），普通字符串不符合该类型要求——这就是TypeScript报错的直接原因。

这种限制是刻意设计的：

• 普通字符串可能包含未转义的恶意代码，比如注入}; body { display: none; /*这类内容破坏全局样式
• 非结构化的字符串无法被Lit的样式预处理系统优化，比如无法进行样式分片、缓存或树摇

2. unsafeCSS的作用 #

unsafeCSS的存在就是为了处理你能确定安全的字符串场景：它会把普通字符串包装成CSSResult类型，绕过css函数的安全校验。但使用时必须确保字符串来源可信（比如硬编码的主题色、静态配置），否则会引入注入风险。

正确实现方式 #

如果要在css模板中使用主题变量，有两种推荐写法：

• 方式一：用unsafeCSS包装可信字符串

import { css, unsafeCSS } from 'lit';

const theme = {
  primary: '#fff'
}

export const baseCss = css`
  :host {
    --primary: ${unsafeCSS(theme.primary)}
  }
`

• 方式二：使用Lit的CSS变量系统（更推荐）
  直接在组件中定义带默认值的CSS变量，后续通过属性或全局样式灵活覆盖：

import { css } from 'lit';

export const baseCss = css`
  :host {
    --primary: #fff; /* 默认值 */
    color: var(--primary);
  }
`

修改样式时无需改动组件代码：

<my-component style="--primary: #000;"></my-component>

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