Calabi--Yau manifolds have risen to prominence in algebraic geometry, in part because of mirror symmetry and enumerative geometry. After Bershadsky--Cecotti--Ooguri--Vafa (BCOV), it is expected that genus 1 curve counting on a Calabi--Yau manifold is related to a conjectured invariant, only depending on the complex structure of the mirror, and built from Ray--Singer holomorphic analytic torsions. To this end, extending work of Fang--Lu--Yoshikawa in dimension 3, we introduce and study the BCOV invariant of Calabi--Yau manifolds of arbitrary dimension. To determine it, knowledge of its behaviour at the boundary of moduli spaces is imperative. We address this problem by proving precise asymptotics along one-parameter degenerations, in terms of topological data and intersection theory. Central to the approach are new results on degenerations of $L^2$ metrics on Hodge bundles, combined with information on the singularities of Quillen metrics in our previous work.