本文详解 vue 3 `<script setup>` 中因 props 命名冲突导致子组件模板无法解析对象属性的根本原因，并提供规范、可复用的修复方案，涵盖声明方式、模板绑定逻辑及最佳实践。</script>
在 Vue 3 的组合式 API 中，<script setup> 语法糖提供了简洁的 props 声明方式，但一个常见却极易被忽视的“逻辑陷阱”是：<strong>在 defineProps() 中定义了一个名为 film 的 prop，却又用同名变量 const film = defineProps(...) 去接收它。这会导致 film 变量本身成为一个包含 film 属性的对象（即 film: { film: {...} }），而非预期的影片数据对象。因此，模板中 {{ film.title }} 实际访问的是 undefined.title，最终渲染失败。</script>
✅ 正确的 Props 声明方式
应始终将 defineProps() 的返回值赋给语义清晰、统一的常量名 —— 推荐使用 props（99% 官方示例与社区约定）：
<!-- FilmComp.vue -->
<script setup>
const props = defineProps({
film: {
type: Object,
required: true,
default: () => ({ title: 'Untitled', year: 2024, genre: '', imgSrc: '' })
}
})
// ✅ 在 script 中访问：props.film.title
console.log('Film data:', props.film)
</script>此时，模板中可直接使用 film（Vue 自动解构 props），无需写 props.film：
<template>
<div class="relative flex w-96 ...">
<div class="...">
<img :src="film.imgSrc" :alt="film.title" /> <!-- ✅ 正确：film 是传入的对象 -->
</div>
<div class="p-6 text-center">
<h4>{{ film.title }}</h4> <!-- ✅ -->
<p>{{ film.genre }}</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill10651" title="蓝湖代码转vue2.0+element-ui"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20e695c2374.jpg" alt="蓝湖代码转vue2.0+element-ui" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill10651" title="蓝湖代码转vue2.0+element-ui">蓝湖代码转vue2.0+element-ui</a>
<p>将静态 Vue 页面(index.vue)改造为动态页面(Custom.vue)；稿源仅限 index.vue、其引用的 CSS 与资源路径，禁止参考仓库内其他文件。Invoke when user wants to transform a static Vue page into a dynamic data-driven page with Element UI components.</p>
</div>
<a href="/xiazai/skill10651" title="蓝湖代码转vue2.0+element-ui" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/cb6835dc7db1" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">前端免费学习笔记（深入）</a>”；</p> <!-- ✅ -->
</div>
<div class="flex justify-center">
{{ film.year }} <!-- ✅ -->
</div>
</div>
</template>⚠️ 关键注意事项
- 禁止命名冲突：切勿声明 const film = defineProps({...}) —— 这会覆盖 props 的自动暴露机制，使模板中 film 指向一个包含 film 属性的对象，而非数据本身。
-
props 常量非必须，但强烈推荐：
- 仅在模板中使用时：可省略 const props =，直接 defineProps({...})（Vue 仍自动暴露 film）；
- 若需在 <script> 中读取/处理 props（如日志、计算、校验），则<strong>必须声明 props 常量，并通过 props.film 访问。</script>
- 类型安全增强：建议配合 TypeScript 或运行时类型校验（如 Object.keys(film).length > 0）确保传入对象结构完整。
? 完整工作流程验证
ListFilms.vue 保持原样（已正确）：
<FilmComp v-for="film in films" :key="film.id" :film="film" />
films 是响应式数组，每个 film 对象结构完整（含 id, title, year, genre, imgSrc），FilmComp 通过 props.film 精准接收并渲染 —— 所有插值与属性绑定均生效。
✅ 总结
| 场景 | 写法 | 是否推荐 | 说明 |
|---|---|---|---|
| 仅模板使用 props | defineProps({ film: Object }) | ⚠️ 可行但不推荐 | 缺乏可维护性，无法在 script 中复用 |
| 模板 + script 均需访问 | const props = defineProps({ film: Object }) | ✅ 强烈推荐 | 清晰、安全、符合 Vue 官方范式 |
| 错误示范 | const film = defineProps({ film: Object }) | ❌ 绝对禁止 | 导致作用域污染与属性访问失效 |
遵循这一规范，不仅能解决当前渲染问题，更能构建出健壮、可调试、易协作的 Vue 3 组件体系。记住：props 是约定俗成的容器名，不是可选别名，而是工程化开发的基石。
